/architecture-deepening

name: architecture-deepening
version: "1.2.0"
description: "Improve architecture across modules by deepening interfaces."
user-invocable: true
command: architecture-deepening
context: fork
allowed-tools:
  - Agent
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
routing:
  triggers:
    - improve architecture
    - improve codebase architecture
    - improve the codebase architecture
    - find architecture improvements
    - deepen architecture
    - find shallow modules
    - architecture improvement
    - module depth analysis
    - deepening opportunities
    - improve module interfaces
    - architecture deepening
  not_for: "local cleanup/refactoring (workflow or planning), feature design (feature-lifecycle), architecture overview/explanation (codebase-overview), or vague complexity reduction; requires cross-module interface or caller-burden evidence"
  pairs_with:
    - review
    - assessment
  complexity: Medium
  category: analysis

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.

| Phase | Reference | Content | |-------|-----------|---------| | Phase 1 | `references/maintenance-lifecycle.md` | Entry rules, recent-change scope, decision memory, candidate schema, typed handoff | | Phase 1 | `references/vocabulary.md` | Shared vocabulary: module, depth, seam, leverage, locality, deletion test | | Phase 2 | `references/interface-design.md` | Patterns for exploring alternative interfaces, deletion test | | Phase 2-3 | `references/deepening-strategies.md` | Dependency categorization, safe deepening, testing strategies |

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 an