Use this skill after completing a code change, bug fix, feature update, migration, or refactoring.
Do not change the normal coding workflow. Do not introduce new theory or terminology. Do not judge the code by abstract design principles first. Do not perform additional refactoring unless explicitly asked.
Instead, reflect on the actual work process while the context is still fresh.
Ask:
- What code did you need to inspect?
- Why did you need to inspect it?
- Where was the real cause, rule, behavior, or decision located?
- Where was the final change made?
- Did the understanding path feel wider or deeper than the change itself?
- What made the change harder than it should have been?
- Which related pieces had to change together?
- Were those related pieces discoverable from the natural starting point?
- Which pieces were disconnected and likely to be missed next time?
- Which existing boundary, layer, module, context, interface, or ownership rule was relevant to this change?
- Did the final change respect that boundary?
- Did the change introduce a new boundary, abstraction, helper, dependency, or shared artifact? If so, is its owner clear under the existing architecture?
Your goal is to identify design or structure issues that increased the amount of context needed for this change, especially disconnected parts of the change surface and boundary-related risks.
Suggest focused improvements that would make future similar changes easier, safer, and less likely to miss something, while preserving the architecture's existing intent.
Do not produce a generic architecture review. Produce a focused post-change reflection based only on what this task actually exposed.
After a change is complete, the agent has valuable temporary knowledge:
- which files had to be inspected
- why they had to be inspected
- where the real rule or cause was located
- which related pieces changed together
- which related pieces were easy to find
- which related pieces were only found by search, failing tests, naming guesses, framework knowledge, manual review, or prior knowledge
- which missing connections may cause future omissions
- which boundaries were crossed or relied on
- which boundaries failed to stop traversal
- whether the final patch respected ownership and dependency direction
Use that knowledge before it disappears.
The most important locality question is:
- If a future developer or agent starts from any meaningful part of this change surface, would they be able to discover the other parts that must be considered together?
- If not, suggest the smallest useful connection.
The most important boundary question is:
- Did this change preserve the existing architecture's boundary, ownership, and placement intent?
- If not, recommend correcting the violation before considering the task complete.
- If the boundary was weak but not violated, record the weakness as boundary pressure instead of silently reshaping the boundary.
In this skill, context cost means all information that had to be loaded, understood, and verified to complete this change safely.
This includes code, tests, types, contracts, configuration, schemas, documentation, runtime behavior, framework conventions, deployment steps, ownership rules, architecture rules, and domain knowledge.
Every non-trivial change has context cost.
This reflection focuses on the part of the context cost that the design made higher than necessary:
- information that was hard to discover
- rules that had no clear owner
- related artifacts that did not point to each other
- boundaries that could not be trusted
- hidden conventions that were not captured as artifacts
- repeated decisions represented in disconnected places
- tests, types, or contracts that failed to reveal the required change surface
- ownership or dependency rules that were unclear at the point of change
- architecture boundaries that the patch almost bypassed or actually violated
The goal is not to eliminate context. The goal is to make the required context smaller, clearer, better connected, and easier to verify for future similar changes, without weakening the architecture's context-routing structure.
Look for locality issues such as:
- business logic scattered across multiple places
- related artifacts that do not point to each other
- repeated representations of the same decision across code, tests, config, frontend, schema, docs, or deployment logic
- framework conventions that are required but not visible near the entry point
- tests that verify behavior but do not explain the rule
- types that are too broad to express the real constraint
- naming that does not reveal responsibility
- documentation or examples missing at the point where they would help
- legacy and new paths implementing the same behavior through different conventions
- cross-system or cross-team dependencies not recorded as contracts, owners, checklists, or consumer lists
Look for boundary issues such as:
- unclear ownership of a rule, behavior, or decision
- weak or vague interface contracts
- hidden coupling between caller and implementation
- implicit side effects across a boundary
- implementation details leaking through a public contract
- caller-specific assumptions entering a shared boundary
- a new helper, abstraction, or shared module with unclear owner
- a shortcut dependency across layers, modules, contexts, or ownership boundaries
- an adapter, registry, layer, or architecture test treated as accidental friction even though it may encode architecture intent
Before suggesting an improvement, identify whether this task touched an existing architectural boundary.
Ask:
- Which existing boundary, layer, module, context, interface, or ownership rule was relevant to this change?
- Did the final change respect that boundary?
- Did the change move a rule, behavior, data access, or decision away from its existing owner?
- Did the change introduce a new boundary? If so, is its owner and placement clear under the higher-level architecture?
- Did the task reveal a weak boundary whose contract failed to stop traversal?
- Did the task introduce a dependency, shortcut, shared abstraction, or contract change that weakens architecture routing?
Rules:
- Respect existing boundaries by default.
- Do not reduce local context cost by moving decisions away from their architectural owner.
- Do not merge concepts across ownership boundaries based only on one observed co-change.
- Do not reshape a shared boundary around the current task's consumer.
- Do not remove an indirection if it serves as an ownership boundary, extension point, protocol boundary, registry, or architecture index.
- Treat architecture tests, dependency rules, visibility rules, and contract tests as guard context, not ordinary friction.
- If this task introduced a boundary violation, recommend correcting it as part of the current change.
- If the boundary was weak but not violated, record it as boundary pressure unless a small contract clarification is enough.
After completing the task, produce a short design reflection with these sections.
Briefly list the important files, modules, tests, interfaces, configs, docs, architecture rules, or runtime behavior that had to be inspected.
For each, explain why it was needed.
Do not list files mechanically.
Good format:
file_or_module: why it mattered for this change
Focus on the reasoning path, not just the file list.
Identify the main reason this change required extra context.
Explain whether the difficulty came from:
- scattered logic
- unclear ownership
- weak boundary
- hidden coupling
- implicit side effect
- missing test signal
- broad type
- misleading naming
- framework convention
- forwarding abstraction
- missing documentation
- legacy/new path divergence
- deployment or config dependency
- social or ownership dependency
- unclear architecture rule
- boundary pressure
Be specific. Avoid vague statements like “the architecture is complex.”
Describe the set of things that turned out to belong to the same change.
Include non-code artifacts if relevant, such as:
- tests
- types
- configs
- schemas
- migrations
- frontend flows
- docs
- scripts
- generated files
- deployment steps
- monitoring
- ownership rules
- external consumers
- architecture tests or dependency rules
This section is about the actual change surface revealed by the task.
Do not assume that one observed co-change proves decision identity. If ownership or future variation is unclear, say so.
Identify any pieces that were not easy to discover from the natural starting point.
Explain how they were discovered:
- direct navigation
- reference lookup
- type lookup
- test failure
- global search
- naming guess
- framework knowledge
- manual review
- prior knowledge
- runtime failure
- deployment failure
- comments or documentation
- architecture rule or ownership note
Call out anything future developers or agents are likely to miss.
This is the locality review: check whether the related pieces of the change were connected well enough.
Identify the existing boundary, layer, module, context, interface, or ownership rule this task touched.
State whether the final change respected it.
Use this form when possible:
- The change stayed within the existing owner of ...
- The change crossed ... but used the existing boundary/protocol.
- The change introduced ... and its owner is ...
- The boundary exists, but its contract was too weak to stop investigation.
- The current patch violates ... because ...
If the patch violates an existing boundary, recommend correcting it before treating the task as complete.
If the boundary was weak but not violated, record it as boundary pressure.
State the structural issue that increased context cost in this task.
Do not label the issue with a broad design principle first. Explain the actual mechanism.
Use this form when possible:
- This change required extra context because ...
- The extra context was needed because ...
- Future similar changes may miss something because ...
- Future similar changes may weaken the architecture because ...
Good examples:
- The rule has no clear owner, so understanding it required reconstructing behavior from several files.
- The boundary exists, but its contract is too weak to stop investigation.
- The same decision is represented in multiple artifacts, but those artifacts do not point to each other.
- The test setup hides an important runtime contract, so passing tests do not clearly explain the real behavior.
- The easiest local patch would bypass the existing ownership boundary, so this task revealed boundary pressure rather than a safe local refactor.
Suggest one focused improvement that reduces future context cost while preserving architecture intent.
Prefer the smallest connection that makes the related change surface easier to discover.
The improvement may be:
- an index: a test name, module note, contract note, README section, ownership note, or checklist
- a stronger executable connection: exhaustive type check, central registry, generated completeness check, contract test, architecture test, or shared test helper
- a small refactor inside an existing owner: moving a scattered rule into its existing owner, clarifying a boundary contract, or removing a forwarding layer that adds no useful understanding and does not serve as an architecture index
Choose a refactor only when the task showed that the disconnected pieces represent the same decision and should have a clearer owner.
Do not infer decision identity from one co-change alone.
Do not suggest broad rewrites. Do not suggest improvements that are merely stylistic. Do not suggest boundary reshaping as a local improvement.
If the improvement would change ownership, dependency direction, public contracts, layer placement, or bounded-context responsibilities, classify it as a separate architecture-focused follow-up.
Explain how the suggestion reduces context cost for future changes.
Be explicit about the mechanism.
For example, explain whether it would:
- make related artifacts discoverable from each other
- give the rule a clearer owner
- let future developers or agents stop at a reliable boundary
- turn hidden knowledge into an artifact
- make omission visible through tests, types, contracts, or checklists
- reduce the number of places that must be inspected before a safe change
- preserve architecture routing by keeping decisions under the correct owner
- make boundary pressure visible without silently weakening the boundary
Avoid vague claims such as “this improves maintainability.”
Classify the suggestion as one of:
- Do now: small, low-risk, directly related to this change, and safe under existing architecture; or required because the current change introduced a boundary violation
- Schedule later: valuable but outside the current task, especially if it changes ownership, dependency direction, public contracts, layer placement, or bounded-context responsibilities
- Just note: interesting signal, but not enough evidence to change yet; often appropriate for weak-boundary observations or one-off co-change evidence
Do not perform the suggested refactoring unless explicitly asked.
Do not suggest broad rewrites. Do not say “improve architecture” without a concrete mechanism. Do not recommend Clean Architecture, DDD, SOLID, DRY, or other labels as the conclusion. Do not turn every inconvenience into a refactoring task. Do not add documentation noise. Do not suggest changes unrelated to the task just completed. Do not reshape boundaries during local post-change reflection. Do not move decisions across ownership boundaries to reduce local traversal. Do not remove architecture indexes merely because they looked like forwarding layers in this task. Do not weaken tests, types, dependency rules, or contracts that enforce architecture intent. Do not perform the suggested improvement unless explicitly asked, except to correct a boundary violation introduced by the current change.
Use this template:
- ...
...
...
...
...
...
...
...
Do now / Schedule later / Just note
...