Architect

Find places where the architecture is the bug. Pattern adapted from mattpocock/skills improve-codebase-architecture.

Glossary — see /codebase-design

/codebase-design is the single source of truth for the deep-module vocabulary — module, interface, implementation, depth, seam, adapter, leverage, locality. Load it for the full definitions and use those terms exactly; never drift into "component," "service," "API," or "boundary."

One-line summary: a deep module puts a lot of behaviour behind a small interface at a clean seam — depth buys leverage for callers and locality for maintainers.

Key heuristics (full treatment in /codebase-design):

• Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
• The interface is the test surface.
• One adapter = hypothetical seam. Two adapters = real seam.
• Side effects belong inside deepened modules, not at the call site.

Process

Step 0 — Resolve company + path

1. Honour explicit [company] [path] arguments
2. Default path to cwd if cwd is inside repos/; else ask via AskUserQuestion
3. Resolve company from manifest if path is under companies/{co}/repos/...

Step 1 — Read the project's domain model + decisions

• Read <repo>/GLOSSARY.md if present (domain glossary)
• Read <repo>/docs/adr/ if present (architectural decisions)
• Read <repo>/.claude/policies/ for any soft architecture rules

If GLOSSARY.md exists, always use its vocabulary in candidate descriptions. ADRs record decisions the skill should not re-litigate; mark candidates that contradict an ADR with _contradicts ADR-NNNN — but worth reopening because…_ and only when friction is real.

Step 2 — Fan out exploration

Spawn parallel Agent subagent_type=Explore calls — one per top-level slice of the target. Each agent:

• Walks its slice
• Notes friction in the architecture glossary's vocabulary
• Returns ≤500 words under fixed headings: Shallow modules, Tightly coupled seams, Untested interfaces, Pass-throughs (deletion-test wins)

Step 3 — Score and rank candidates

For each friction point, assign:

Dimension	Question	Score 1-3
Deletion test	Would deleting this concentrate complexity?	3 = yes, strong; 1 = no, just moves it
Leverage	Behaviour-to-interface ratio after deepening	3 = high (lots behind a small interface); 1 = low
Locality	Change/bug concentration after deepening	3 = single place; 1 = stays scattered
Test surface	Does the deepened interface become a useful test seam?	3 = yes, replaces N small unit tests; 1 = no improvement
Cost	Refactor effort	3 = small; 1 = large

Sum to a single rank. Present top 5–10.

Step 4 — Present candidates (no edits yet)

Output via numbered list, NOT AskUserQuestion first (the list is too long for a 4-option question — present then ask):

## Candidate N — <name in GLOSSARY.md vocabulary>

**Files:** <file:line refs>
**Problem:** <friction described in glossary terms>
**Solution (plain English):** <what would change>
**Benefits:** locality: <X>, leverage: <Y>, test improvement: <Z>
**Score:** <total> (deletion: <d>, leverage: <l>, locality: <lo>, test: <t>, cost: <c>)
**Recommendation:** <Strong / Worth exploring / Speculative>
**ADR conflicts:** <none / contradicts ADR-NNNN — re-open because …>

The Recommendation badge is a plain-English read on top of the numeric score: Strong = high score and low risk, tackle first; Worth exploring = real friction but non-trivial cost or uncertainty; Speculative = plausible but the case isn't proven yet. Show both — the number ranks, the badge conveys confidence.

Then ask via AskUserQuestion (multiSelect: true): "Which candidates do you want to explore?" with up to 4 options (paginate if more).

Step 5 — Grilling loop per picked candidate

For each picked candidate, drop into a one-question-at-a-time design conversation:

• What constraints does the deepened module need to satisfy?
• What goes behind the seam? What stays in callers?
• What's the interface — types, invariants, error modes, ordering, config?
• What tests survive the change? What new tests does the seam enable?
• Are there alternative interface shapes worth considering?

Design it twice. When the interface shape is non-obvious, don't settle on the first design. Reuse HQ's Explore fan-out: spin up parallel Agent sub-agents to design the deepened interface several radically different ways (e.g. a data-oriented shape, a callback/handler shape, a builder/pipeline shape). Then compare the returns on depth (behaviour-per-interface), locality (where change concentrates), and seam placement — and bring the winner (or a hybrid) back into the grilling conversation. See /codebase-design's DESIGN-IT-TWICE.md for the pattern.

Side effects happen inline:

• Naming a deepened module after a concept not in GLOSSARY.md → add the term lazily.
• Sharpening a fuzzy term during the conversation → update GLOSSARY.md right there.
• User rejects with a load-bearing reason → offer /adr, framed as: "Want me to record this as an ADR so future architecture passes don't re-suggest it?" Only offer for reasons future explorers would actually need; skip ephemeral or self-evident ones.

Do not write the refactor. This skill produces the design and the case for it. Implementation goes through /run-project or /tdd.

Step 6 — Save report

Save to workspace/reports/{slug}-architect.md:

# Architect: <repo> @ <path>

**HEAD:** <sha>
**GLOSSARY.md present:** yes / no
**ADRs present:** <count>

## Candidates

### 1. <name> — DECISION: <explored / declined / pending>
<full block from Step 4>

#### Grilling notes (if explored)
<key questions + answers>

#### Outcome
- ADR opened: <yes / no — link>
- Implementation queued: <yes — /prd or /run-project ref / no>

### 2. …

Output integration

Outcome	Next step
Candidate explored, design crystallised	/prd (PRD with userStories[] for the refactor) or /run-project (if scope is small)
Candidate rejected with load-bearing reason	/adr
New domain term surfaced	already updated GLOSSARY.md inline
Code change shouldn't proceed without test seam	hand off to /tdd
Pre-PR review on changed files only	/review --architect-pass

Rules

• Never edit production code in this skill. Candidates and design only.
• Never propose interfaces in Step 4 — wait for the user to pick before designing.
• Always use GLOSSARY.md vocabulary for the domain. Always use the architecture glossary for structure terms.
• Don't list every theoretical refactor an ADR forbids. Only surface ADR-contradicting candidates when the friction is real enough to warrant revisiting the decision.
• Two-adapter rule before declaring a seam. A single adapter is a hypothetical seam, not a real one — don't recommend abstracting until at least two concrete users exist.

Cross-references

• /diagnose Phase 6 — entry point when "no good test seam" is the diagnosis.
• /review --architect-pass — narrower scope (changed files only); same heuristics.
• /adr — capture decisions that should not be re-litigated.
• /prd — turn explored candidates into PRD + userStories.
• /tdd — refactor under test once the candidate is designed.
• Pattern source: mattpocock/skills improve-codebase-architecture (repos/public/skills/skills/engineering/improve-codebase-architecture/SKILL.md).