Architecture Deepening

Architecture Deepening

Find shallow modules and propose deepening opportunities. Not a code review -- does not find bugs or style violations. Finds modules where the interface is too close to the implementation, where users must understand internals to use the API, and where small interface changes would absorb disproportionate complexity.

When to use: After codebase onboarding or review when improvement was requested, before a cross-module feature, after a fix exposes a missing test seam, or when callers repeatedly need source knowledge or multi-module coordination.

Differs from full-repo-review: Full-repo-review finds defects. This skill finds structural improvement opportunities. Pair well: run full-repo-review first to fix defects, then architecture-deepening to raise the bar.

Deep References

Load on demand when working in the named phase.

Instructions

Run phases in order until a terminal gate. Survey and design keep source code read-only; Write/Edit apply only to user-approved decision records after selection. Existing delivery workflows own code changes. The user selects candidates and decides whether a handoff proceeds.

Language-agnostic. Vocabulary and strategies apply to Go, Python, TypeScript, or any codebase with module boundaries.

Phase 1: EXPLORE

Goal: Identify shallow modules -- where the interface exposes too much implementation detail.

Step 1: Choose an evidence-fed scope

Read references/maintenance-lifecycle.md. Use the user's named directory/package first. Otherwise start from the review, overview, feature, or fixed-bug evidence that triggered the run. With no such artifact, rank module paths changed in the last 50 commits and inspect the top bounded set. Recent change raises priority; it is not proof of shallowness. Widen once only when the initial scope has no usable evidence and the request is repository-wide.

Read prior architecture decisions before producing candidates. Suppress a matching stable rejection unless its recorded assumptions changed.

Then scan the chosen scope for module boundaries.

find . -name "go.mod" -o -name "package.json" -o -name "pyproject.toml" -o -name "__init__.py" -o -name "index.ts" -o -name "mod.rs" 2>/dev/null | head -50

# Exported symbols per package (Go)
grep -rn "^func [A-Z]" --include="*.go" | cut -d: -f1 | sort | uniq -c | sort -rn | head -20

# Public exports (TypeScript)
grep -rn "^export " --include="*.ts" --include="*.tsx" | cut -d: -f1 | sort | uniq -c | sort -rn | head -20

Step 2: Apply shallowness signals

Read references/vocabulary.md for full vocabulary. A module is shallow when:

• Interface nearly as complex as implementation (high surface-area-to-depth ratio)
• Users must read source to understand how to call it
• Setup requires knowledge of internal state
• Error messages expose implementation details
• Multiple modules must coordinate for a single logical operation

For each candidate, cite the interface, caller burden, affected callers, change evidence, and prior-decision match. Score each: HIGH (clear shallowness, high-leverage fix), MEDIUM (some shallowness, moderate leverage), LOW (minor, low impact). Rank only candidates that meet the evidence floor in maintenance-lifecycle.md.

Step 3: Identify seams

For HIGH-scored modules, identify seams -- natural boundaries where the module could absorb more responsibility. See references/vocabulary.md for seam types (data, protocol, temporal).

Gate: Emit either (a) ranked, evidence-backed candidates with seam analysis or (b) the no-findings record plus its terminal typed handoff from maintenance-lifecycle.md. Validate no-findings inline through scripts/handoff.py validate --stdin; it creates no file. Both pass. No-findings closes the run; candidate count is never padded.

Phase 2: PRESENT CANDIDATES

Goal: Show findings, let the user choose, then explore alternatives for selected candidates.

Step 1: Present findings table

| Rank | Module | Depth Score | Evidence | Seam | Leverage | Prior Decision |
|------|--------|-------------|----------|------|----------|----------------|
| 1 | pkg/config | HIGH | 12 callers construct the same internal shape | Data seam | High | none |
| 2 | internal/auth | MEDIUM | 4 callers coordinate refresh state | Protocol seam | Medium | assumptions changed |

For each: what it does today, why it is shallow, the exact interface and caller evidence, where the seam is, leverage, change likelihood, and any prior decision.

Step 2: Get user input

Ask which candidate to explore, reject, or defer. Stop before interface design until the user chooses. Rejection and deferral may close immediately with a terminal handoff. Persist them only when the durability test passes and the user approves the write.

Step 3: Explore interface alternatives

Read references/interface-design.md and references/deepening-strategies.md. Design 2-3 alternative interfaces per candidate:

• New interface signature (function names, parameters, return types)
• What moves behind the interface (what callers no longer need to know)
• Deletion test result: what caller code can be deleted
• Trade-offs: flexibility lost, edge cases needing escape hatches

Gate: A selected candidate has at least 2 alternatives with deletion-test results. Rejection or deferral is a valid terminal result after its close handoff; durable state is optional and consent-gated.