Improve Codebase Architecture

Surface architectural friction and propose "deepening opportunities" — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

Informed by: /codebase-design vocabulary, CONTEXT.md (domain glossary), docs/adr/.

Step 1 — Explore

Scope before you scan — YAGNI. Focus on recently-changed parts of the codebase:

1. Check git log --oneline -20 for recently-active areas
2. Read CONTEXT.md and relevant ADRs
3. Use an Explore agent to walk the scoped code organically, noting friction points

For each suspected shallow module, apply the deletion test: "Would deleting it concentrate complexity in one place, or just move it elsewhere?" If deletion would barely be noticed, it's a middleman.

Step 2 — Present candidates as HTML report

Write a self-contained HTML file to $TMPDIR/architecture-review-<timestamp>.html (nothing lands in the repo). Open it for the user.

Report requirements:

• Tailwind via CDN for layout/styling
• Mermaid via CDN for diagrams (call graphs, dependencies, sequences)
• Mix Mermaid with hand-crafted CSS/SVG for editorial visuals (mass diagrams, cross-sections, before/after comparisons)
• Each candidate gets a before/after visualisation
• Each candidate card shows confidence: Strong, Worth exploring, or Speculative
• Ends with a Top recommendation section (which to tackle first, why)
• Uses CONTEXT.md vocabulary for domain terms
• Uses /codebase-design vocabulary for architecture terms (depth, seam, module, adapter, leverage, locality)

Does NOT propose interfaces yet. After presenting, ask: "Which of these would you like to explore?"

ADR conflicts

Only surface when friction is real enough to warrant reopening the ADR. Don't flag every old ADR as "maybe outdated" — that's noise.

Step 3 — Grilling loop

Once the user picks a candidate:

1. Run /grilling to walk the decision tree — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive
2. Run /domain-modeling inline as vocabulary evolves during the discussion
3. If the decision is non-trivial (hard to reverse, surprising, real trade-off), write an ADR
4. Once the decision crystallises, create implementation tickets on the wayfinder map for the refactor

Integration with the project-onboard flow

Post-implementation (wayfinder orchestration)

After all implementation tickets complete and code-review passes, if doc_tier is "app" or "system", wayfinder offers this skill as an optional architecture review. The user can accept or decline.

Bug escalation (diagnosing-bugs Phase 6)

When a bug post-mortem reveals that "no good test seam exists" — the architecture is the problem — diagnosing-bugs creates a wayfinder ticket that routes here.

Standalone

The user can invoke this directly at any time as periodic hygiene. Recommended cadence: once every few days of active development.

What this skill must never do

• Never propose interfaces during Step 2 (that's Step 3's job after grilling)
• Never commit the HTML report to the repo (it goes to $TMPDIR)
• Never rewrite code during the grilling loop — output is decisions and tickets, not implementation
• Never flag ADRs as "outdated" without concrete friction evidence