implementation-structure-design
Registry Trigger
Use when
- Semantic-compatible reuse inside an established owner is disputed.
- Method, class, file, or test placement inside an established owner is disputed.
- Co-location or private extraction inside an established owner is disputed.
- An owner-private new structure inside an established owner is disputed.
- A deliberate separate implementation inside an established owner is disputed.
- Generated-source separation or placement inside an established owner is disputed.
Do not use when
- Cross-module ownership, dependency direction, public/shared/exported surfaces, cycles, or shared packages change; use
module-boundary-design.
- A distributable SDK or library contract changes; use
sdk-library-contract-design.
- Architecture style, layer responsibilities, or extension compatibility is primary; use
architecture-style-selection, layered-architecture-design, or extensibility-design.
- Model translation, side-effect ordering, persistence semantics, or transport contracts are primary; use their owning capability.
- Behavior-preserving movement is primary; use
refactoring. For local flow or readability, use code-clarity-maintainability.
- The current owner and repository convention already fix placement.
Skill Role
Choose reuse, placement, visibility, extraction, generated-source separation, and test location inside one fixed owner. Do not redefine business rules, external contracts, or module architecture.
High-Value Rules
- Consume an accepted need for structure from
minimal-correct-implementation; this capability decides only semantic-compatible reuse and placement inside the accepted owner.
- Reuse only when semantics, authority, failure, lifecycle, and evolution match; similarity is insufficient.
- Keep a deliberate separate implementation when those forces differ; record drift controls and its delete condition.
- Place code with the owner of its change reason, state, invariant, effect, protocol, lifecycle, and tests; compare co-location and private extraction before new structure.
- Route exports, cross-owner/shared modules, public surfaces, dependencies, cycles, or distributable artifacts to
module-boundary-design or sdk-library-contract-design.
- Trace generated placement as
editable source -> generator/template/config -> artifact -> committed/derived policy -> regen/freshness check.
- Separate semantic from mechanical generated diffs; use
repository-context-map for authority and build-tool-professional-usage for graph, regeneration, and artifact policy.
- After placement is fixed, route behavior-preserving movement to
refactoring; keep naming, guards, and local flow in code-clarity-maintainability.
Anti-Patterns
- Using framework layers, directory conventions, or
shared/common/utils as owners.
- Creating parallel helpers or vague managers before checking the semantic owner and boundary.
- Splitting by size thresholds into ownerless files or mixed lifecycles.
- Exporting private helpers only for tests.
- Moving business rules into transport, persistence, DTO, or generic utility layers.
Stop Conditions
Stop when placement would change an accepted owner, public contract, model semantics, effect order, resource lifetime, persistence, API behavior, or another observable without authority and proof.
Stop when generated-source authority is unknown or a requested edit bypasses its accepted generator, template, or configuration authority.
Output Contract
- Implementation placement decision with accepted existence input, inspected reuse and deliberate-separation candidates, selected owner-private location, visibility, and co-location/extraction rationale. It records semantic and generated-source handling, tests/fixtures, evidence and validation plan, proof limits, delete/drift conditions, specialist handoffs, and residual risks.
Targeted References
| Path |
Type |
Load when |
Do not load when |
Required by |
Required output |
| object module decomposition |
targeted |
co-location extraction visibility split merge or test placement remains disputed inside one owning module |
the current owner and change lifecycle already fix the object or file boundary |
task-agent, review-agent, analysis-agent |
decision-record, validation-plan, proof-limit, residual-risk |
| reuse and placement |
targeted |
repository-local reuse leaves more than one semantic-compatible owner-private placement or deliberate-separation decision |
one semantic-compatible owner-private placement is already proved |
task-agent, review-agent, analysis-agent |
selected-approach, validation-plan, proof-limit, residual-risk |
| evidence patterns |
evidence-pattern |
placement generated-source or deliberate-separation claims need current owner consumer and freshness evidence |
no placement or source-authority claim awaits closure |
task-agent, review-agent, analysis-agent |
evidence-record, validation-plan, proof-limit, residual-risk |
1---2name: implementation-structure-design3description: `analysis-agent`/`task-agent`/`review-agent`: use when reuse or method/class/file placement inside one owner is disputed; skip fixed placement or cross-module ownership.4---5
6# implementation-structure-design
7
8## Registry Trigger
9
10**Use when**
11
12- Semantic-compatible reuse inside an established owner is disputed.
13- Method, class, file, or test placement inside an established owner is disputed.
14- Co-location or private extraction inside an established owner is disputed.
15- An owner-private new structure inside an established owner is disputed.
16- A deliberate separate implementation inside an established owner is disputed.
17- Generated-source separation or placement inside an established owner is disputed.
18
19**Do not use when**
20
21- Cross-module ownership, dependency direction, public/shared/exported surfaces, cycles, or shared packages change; use `module-boundary-design`.
22- A distributable SDK or library contract changes; use `sdk-library-contract-design`.
23- Architecture style, layer responsibilities, or extension compatibility is primary; use `architecture-style-selection`, `layered-architecture-design`, or `extensibility-design`.
24- Model translation, side-effect ordering, persistence semantics, or transport contracts are primary; use their owning capability.
25- Behavior-preserving movement is primary; use `refactoring`. For local flow or readability, use `code-clarity-maintainability`.
26- The current owner and repository convention already fix placement.
27
28## Skill Role
29
30Choose reuse, placement, visibility, extraction, generated-source separation, and test location inside one fixed owner. Do not redefine business rules, external contracts, or module architecture.
31
32## High-Value Rules
33
34- Consume an accepted need for structure from `minimal-correct-implementation`; this capability decides only semantic-compatible reuse and placement inside the accepted owner.
35- Reuse only when semantics, authority, failure, lifecycle, and evolution match; similarity is insufficient.
36- Keep a deliberate separate implementation when those forces differ; record drift controls and its delete condition.
37- Place code with the owner of its change reason, state, invariant, effect, protocol, lifecycle, and tests; compare co-location and private extraction before new structure.
38- Route exports, cross-owner/shared modules, public surfaces, dependencies, cycles, or distributable artifacts to `module-boundary-design` or `sdk-library-contract-design`.
39- Trace generated placement as `editable source -> generator/template/config -> artifact -> committed/derived policy -> regen/freshness check`.
40- Separate semantic from mechanical generated diffs; use `repository-context-map` for authority and `build-tool-professional-usage` for graph, regeneration, and artifact policy.
41- After placement is fixed, route behavior-preserving movement to `refactoring`; keep naming, guards, and local flow in `code-clarity-maintainability`.
42
43## Anti-Patterns
44
45- Using framework layers, directory conventions, or `shared`/`common`/`utils` as owners.
46- Creating parallel helpers or vague managers before checking the semantic owner and boundary.
47- Splitting by size thresholds into ownerless files or mixed lifecycles.
48- Exporting private helpers only for tests.
49- Moving business rules into transport, persistence, DTO, or generic utility layers.
50
51## Stop Conditions
52
53Stop when placement would change an accepted owner, public contract, model semantics, effect order, resource lifetime, persistence, API behavior, or another observable without authority and proof.
54
55Stop when generated-source authority is unknown or a requested edit bypasses its accepted generator, template, or configuration authority.
56
57## Output Contract
58
59- Implementation placement decision with accepted existence input, inspected reuse and deliberate-separation candidates, selected owner-private location, visibility, and co-location/extraction rationale. It records semantic and generated-source handling, tests/fixtures, evidence and validation plan, proof limits, delete/drift conditions, specialist handoffs, and residual risks.
60
61## Targeted References
62
63| Path | Type | Load when | Do not load when | Required by | Required output |
64|---|---|---|---|---|---|
65| [object module decomposition](references/object-module-decomposition.md) | targeted | co-location extraction visibility split merge or test placement remains disputed inside one owning module | the current owner and change lifecycle already fix the object or file boundary | task-agent, review-agent, analysis-agent | decision-record, validation-plan, proof-limit, residual-risk |
66| [reuse and placement](references/reuse-and-placement.md) | targeted | repository-local reuse leaves more than one semantic-compatible owner-private placement or deliberate-separation decision | one semantic-compatible owner-private placement is already proved | task-agent, review-agent, analysis-agent | selected-approach, validation-plan, proof-limit, residual-risk |
67| [evidence patterns](references/evidence-patterns.md) | evidence-pattern | placement generated-source or deliberate-separation claims need current owner consumer and freshness evidence | no placement or source-authority claim awaits closure | task-agent, review-agent, analysis-agent | evidence-record, validation-plan, proof-limit, residual-risk |
machenjie