code-architecture
/code-architecture
Scan a codebase for deepening opportunities, such as shallow modules, hypothetical seams and scattered state, against the h2xd:code-quality bar and its smells, report them ranked, then grill through the one the user picks with h2xd:plan-grill. A chosen reshape that is hard to reverse goes through h2xd:docs-adr. Use when the user asks for an architecture review, wants to find refactoring targets, says the code is hard to change or test, or asks where to deepen modules.
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Scan a codebase for deepening opportunities, such as shallow modules, hypothetical seams and scattered state, against the h2xd:code-quality bar and its smells, report them ranked, then grill through the one the user picks with h2xd:plan-grill. A chosen reshape that is hard to reverse goes through h2xd:docs-adr. Use when the user asks for an architecture review, wants to find refactoring targets, says the code is hard to change or test, or asks where to deepen modules.
Original author description
Scan a codebase for deepening opportunities, such as shallow modules, hypothetical seams and scattered state, against the h2xd:code-quality bar and its smells, report them ranked, then grill through the one the user picks with h2xd:plan-grill. A chosen reshape that is hard to reverse goes through h2xd:docs-adr. Use when the user asks for an architecture review, wants to find refactoring targets, says the code is hard to change or test, or asks where to deepen modules.
How it works
- Steps
- Do
- Don't
SKILL.md preview
--- name: code-architecture description: Scan a codebase for deepening opportunities, such as shallow modules, hypothetical seams and scattered state, against the h2xd:code-quality bar and its smells, report them ranked, then grill through the one the user picks with h2xd:plan-grill. A chosen reshape that is hard to reverse goes through h2xd:docs-adr. Use when the user asks for an architecture review, wants to find refactoring targets, says the code is hard to change or test, or asks where to deepen modules. disable-model-invocation: true --- # Improve architecture When renaming one field edits eleven files, the code has shallow modules. Agents copy the shape they find, so the next change edits a twelfth. This skill finds where merging or moving code gives a deep module: a small interface over a lot of behavior. It turns the one the user picks into decisions. Use the words in [`vocabulary.md`](vocabulary.md) in every candidate, report line and question. Name domain things by their `h2xd:docs-glossary` heading. The glossary paths are in `docs.glossaries` of `agents.config.json`. ## Steps ### 1. Scope Deepening pays off first where code changes often. Pick the scope first. - When the user named a module, a directory or a pain point, scope to it and skip the history. - Otherwise list the most changed files in recent history: ```sh git log --since="6 months ago" --name-only --format= | sort | uniq -c | sort -rn | head -40 ``` Group the top files by directory. When no group stands out, scan the whole source tree. For each area in scope, run `node scripts/find-docs.ts --links-to <path>`. Note the decision records and wiki pages it lists. Done when you have a list of paths in scope, ranked by change count, with the records and pages that cover them. ### 2. Explore Start one subagent with a fresh context to walk the scope. Use the CLI's subagent tool, such as Agent. On a large scope, start one per area in parallel. Give each one the path to [`explore-brief.md`](explore-brief.md), its paths and hot spots, the glossary paths, and the record paths from step 1. When the subagents return, check each candidate yourself: 1. Open its files and confirm the quoted problem is real. 2. Run the deletion test from `vocabulary.md`. Drop a candidate where deleting or merging moves complexity without concentrating it. 3. Drop a candidate that an accepted decision record forbids, unless the friction is strong enough to reopen the record. Keep that one and name the record. Done when every kept candidate has confirmed files, a smell, a dependency category and evidence. ### 3. Report Rank the candidates and print the report, worst first: ``` 🔴 <deepening>: <problem in one sentence>. <the change in one sentence>. Files: <paths> · Smell: <name> · Dependencies: <category> Wins: <locality and leverage gains, which tests get simpler> 🟡 <deepening>: ... 🟢 <area>: walked, deep enough, nothing to change. ``` - 🔴 Strong. The friction shows in recent commits or bug fixes, and the deletion test passes. - 🟡 Worth exploring. The smell is clear, but recent history does not show it hurting yet. - 🟢 An area walked and found deep. List these so the user sees the coverage. When a candidate contradicts a decision record, add a line: `Contradicts <record path>: <why it is worth reopening>.` End with your top pick and one sentence on why. Propose no interface yet. Ask which candidate to explore, with clickable options, through the CLI's question tool, such as AskUserQuestion. Your top pick is the first option. Done when the user picked a candidate, or said none. ### 4. Grill the pick Read the picked candidate's files in full. Then run `h2xd:plan-grill` on its design tree. Cover at least: - The constraints the deepened module must keep. - Which modules merge, and which callers move to the new interface. - Where the seam goes, and which adapters sit at it. - What the implementation hides. - Which old tests are deleted and which new tests sit at the interface. When the user wants to compare interfaces, follow [`design-it-twice.md`](design-it-twice.md). Its result is one more decision in the tree. While grilling, keep the glossaries current with `h2xd:docs-glossary`: - A deepened module named after a concept with no entry gets an entry. - A term the conversation sharpened gets its entry updated. Done when the user confirmed the decision table from `h2xd:plan-grill`. ### 5. Record Run step 1 of `h2xd:docs-adr` on the confirmed reshape. When the reshape is hard to reverse, surprising without context and a real trade-off, write the record with `h2xd:docs-adr`. When the user rejected the candidate for a reason a later review would need, ask: "Record this as a decision so later reviews do not suggest it again?" Write it with `h2xd:docs-adr` on a yes. Skip reasons that only hold today, such as "no time this sprint". Done when the record exists and `node scripts/lint-docs.ts` exits 0, or `h2xd:docs-adr` step 1 said no record is needed, or the user declined. ### 6. Hand over Summarize the confirmed decisions and the record path. Offer to make the change. When the user says yes, follow `h2xd:code-quality`: move every caller in the same change, replace the old tests as `vocabulary.md` says, and run `h2xd:prove-tests` on the new ones. Done when the user has the summary and chose to build now, later or never. ## Do - Scope by recent change before scanning anything. - Quote the code or count the commits behind every candidate. - List the areas that passed, so the report shows its coverage. - Ask which candidate to explore before proposing any interface. ## Don't - Don't write "component", "service", "API" or "boundary". Use "module", "interface" and "seam" from `vocabulary.md`. - Don't propose a seam with one adapter. Name the second adapter, or merge. - Don't list every refactor a decision record forbids. Keep only the ones worth reopening it, and name the record. - Don't keep the old shallow-module tests next to the new ones. Delete them once the interface tests cover the behavior. - Don't change code during the review. Change it in step 6, after the user confirms.
Files in this package (4)
- SKILL.md 6 KB
- design-it-twice.md 2 KB
- explore-brief.md 2 KB
- vocabulary.md 3 KB
Versions
The database has no other skills named code-architecture.
Database snapshot: 13.11.2026 · package version d2e315f246de (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100jidoka-improve-architecture
Scan a codebase for deepening opportunities, report them as Markdown in the chat, grill through the one the user picks and file it as a spec. Use when the user asks to find refactoring or deepening opportunities, or about large or hard-to-change modules. - 100module-deepening
Use when looking for shallow modules worth deepening, deciding where a seam belongs, or designing a chosen module''s interface several ways before refactoring. Scan mode renders candidates as an offline HTML report; design mode compares alternative interfaces and recommends one.… - 100improve
Find deepening opportunities in a codebase — refactors that turn shallow modules into deep ones for better testability and AI-navigability. Use when the user wants to improve architecture, surface architectural friction, consolidate tightly-coupled modules, find shallow… - 95improve-codebase-architecture
Explicitly scan existing product code for evidence-backed deep-module opportunities, render a safe offline report, and explore one user-selected refactor without implementing it. Use for broad maintenance discovery of shallow modules, scattered policy, leaky seams, repeated… - 100improve-codebase-architecture
Explore a codebase to find opportunities for architectural improvement by deepening shallow modules (John Ousterhout, "A Philosophy of Software Design"). Use when the user says "improve architecture", "find refactoring opportunities", "make this more testable", "this codebase is… - 100codebase-improve-architecture
Explore a codebase to find opportunities for architectural improvement, focusing on making the codebase more testable by deepening shallow modules. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable.