page-component-decomposition
Registry Trigger
Use when
- decompose page into components responsibilities props and reusable boundaries
Do not use when
- no task-local page component decomposition decision is required
Skill Role
Define component responsibility, state and effect ownership, data-flow contracts, reuse boundaries, rendering and interaction consequences, and decomposition evidence. Exclude product-flow design and framework implementation.
High-Value Rules
- Decompose by ownership and change reason. Group behavior that shares state, lifecycle, policy, or release responsibility, and split when distinct responsibilities can evolve behind a stable contract.
- Place state at the narrowest common owner. Keep local interaction state near its consumers and share it only across real coordination boundaries. Server or authoritative state semantics remain unduplicated in view components.
- Make component contracts semantic. Pass domain-relevant values, actions, status, and errors with clear optionality and ownership; avoid broad context, mutable objects, or callback bags that hide dependencies.
- Separate orchestration from presentation where it changes evidence. Keep fetching, mutation, routing, permission context, and effect coordination outside reusable presentation units when separation enables clearer ownership and tests.
- Reuse only across aligned behavior. Extract a shared component when interaction semantics, accessibility, visual states, and expected evolution match; prefer local duplication over a premature abstraction joining unrelated change reasons.
- Preserve rendering and interaction boundaries. Account for loading, error, empty, permission, responsive, focus, hydration, and expensive-render behavior that may cross the proposed split.
- Prove integration after the split. Verify public behavior, state transitions, effect ordering, accessibility, and affected consumers, while stating surfaces and framework behavior left uninspected.
Anti-Patterns
- Split by file length, markup count, or visual boxes without identifying ownership and independent change.
- Lift state globally for convenience or hide required data and effects behind implicit context.
- Create a generic component from one consumer, then accumulate flags that encode separate products or workflows.
Stop Conditions
Escalate when state authority or effect ownership is unclear, the split crosses permission or transaction boundaries, or reuse couples independent owners. Also escalate when rendering semantics are uncertain, or current tests cannot distinguish behavior preservation from structural movement.
Output Contract
- component decomposition decision with responsibility boundaries, state and effect owners, semantic contracts, reuse rationale, rendering consequences, integration evidence, and residual risks
Targeted References
| Path |
Type |
Load when |
Do not load when |
Required by |
Required output |
| benchmarks and patterns |
benchmark-pattern |
responsibility state ownership reuse or orchestration admits competing decompositions |
one existing component boundary fully owns the changed behavior |
task-agent, analysis-agent |
option-comparison, selected-approach |
| checklist |
decision-checklist |
page change mixes workflow state side effects rendering or permissions |
local component change preserves established responsibilities and state ownership |
task-agent, analysis-agent |
checklist-result, residual-risk |
| evidence patterns |
evidence-pattern |
reuse ownership accessibility or decomposition claims need current proof |
current consumers stories tests and source prove each claim |
task-agent, analysis-agent |
evidence-record, proof-limit, residual-risk |
1---2name: page-component-decomposition3description: `analysis-agent`/`task-agent`: use when page components, props, state ownership, reuse, or decomposition boundaries change; skip when no component-structure decision exists.4---5
6# page-component-decomposition
7
8## Registry Trigger
9
10**Use when**
11
12- decompose page into components responsibilities props and reusable boundaries
13
14**Do not use when**
15
16- no task-local page component decomposition decision is required
17
18## Skill Role
19
20Define component responsibility, state and effect ownership, data-flow contracts, reuse boundaries, rendering and interaction consequences, and decomposition evidence. Exclude product-flow design and framework implementation.
21
22## High-Value Rules
23
24- **Decompose by ownership and change reason.** Group behavior that shares state, lifecycle, policy, or release responsibility, and split when distinct responsibilities can evolve behind a stable contract.
25- **Place state at the narrowest common owner.** Keep local interaction state near its consumers and share it only across real coordination boundaries. Server or authoritative state semantics remain unduplicated in view components.
26- **Make component contracts semantic.** Pass domain-relevant values, actions, status, and errors with clear optionality and ownership; avoid broad context, mutable objects, or callback bags that hide dependencies.
27- **Separate orchestration from presentation where it changes evidence.** Keep fetching, mutation, routing, permission context, and effect coordination outside reusable presentation units when separation enables clearer ownership and tests.
28- **Reuse only across aligned behavior.** Extract a shared component when interaction semantics, accessibility, visual states, and expected evolution match; prefer local duplication over a premature abstraction joining unrelated change reasons.
29- **Preserve rendering and interaction boundaries.** Account for loading, error, empty, permission, responsive, focus, hydration, and expensive-render behavior that may cross the proposed split.
30- **Prove integration after the split.** Verify public behavior, state transitions, effect ordering, accessibility, and affected consumers, while stating surfaces and framework behavior left uninspected.
31
32## Anti-Patterns
33
34- Split by file length, markup count, or visual boxes without identifying ownership and independent change.
35- Lift state globally for convenience or hide required data and effects behind implicit context.
36- Create a generic component from one consumer, then accumulate flags that encode separate products or workflows.
37
38## Stop Conditions
39
40Escalate when state authority or effect ownership is unclear, the split crosses permission or transaction boundaries, or reuse couples independent owners. Also escalate when rendering semantics are uncertain, or current tests cannot distinguish behavior preservation from structural movement.
41
42## Output Contract
43
44- component decomposition decision with responsibility boundaries, state and effect owners, semantic contracts, reuse rationale, rendering consequences, integration evidence, and residual risks
45
46## Targeted References
47
48| Path | Type | Load when | Do not load when | Required by | Required output |
49|---|---|---|---|---|---|
50| [benchmarks and patterns](references/benchmarks-and-patterns.md) | benchmark-pattern | responsibility state ownership reuse or orchestration admits competing decompositions | one existing component boundary fully owns the changed behavior | task-agent, analysis-agent | option-comparison, selected-approach |
51| [checklist](references/checklist.md) | decision-checklist | page change mixes workflow state side effects rendering or permissions | local component change preserves established responsibilities and state ownership | task-agent, analysis-agent | checklist-result, residual-risk |
52| [evidence patterns](references/evidence-patterns.md) | evidence-pattern | reuse ownership accessibility or decomposition claims need current proof | current consumers stories tests and source prove each claim | task-agent, analysis-agent | evidence-record, proof-limit, residual-risk |
machenjie