| name | arch-lens |
| description | Explores a codebase for architectural friction through the lens of Ousterhout's deep-module principle (small interface, large implementation). Seven-step interactive workflow: an Explore sub-agent navigates the codebase organically — the friction it experiences IS the signal. Surfaces candidate clusters with coupling reasons, call patterns, shared types, dependency categories, and existing tests that a boundary test would replace. User picks what to explore, frames the problem, then 3–4 parallel sub-agents design competing deep-module interfaces. Chosen design becomes a structured RFC action file readable by GitHub MCP or ROVO (Jira) MCP. Use when the user says "arch review", "find shallow modules", "module depth", "deep module", "Ousterhout", "testability audit", "surface coupling", "design interfaces", "RFC issues", or "architectural friction".
|
| allowed-tools | Read Grep Glob Write Bash(git *) |
| argument-hint | [path/to/scope] |
| compatibility | Requires git for churn analysis. No other external tools required. |
Arch Lens
Seven-step interactive architectural review. An Explore sub-agent navigates the
codebase the way a developer would — the confusion, file-bouncing, and untestable
seams it encounters are the findings. No checklists, no rigid heuristics.
Deep module: small interface surface hiding a large, self-contained implementation.
Lets callers test at the boundary. Lets AI agents reason without reading internals.
Quick start
- If a path argument is given, scope to that directory; otherwise whole repo
- Load
${CLAUDE_SKILL_DIR}/references/WORKFLOW.md — full step-by-step instructions
- Load
${CLAUDE_SKILL_DIR}/references/DETECTION-PATTERNS.md
- Load
${CLAUDE_SKILL_DIR}/references/INTERFACE-DESIGN.md
- Load
${CLAUDE_SKILL_DIR}/references/RFC-FILE-FORMAT.md
- Execute the seven steps in WORKFLOW.md
Workflows
| Step | What happens | Requires user input |
|---|
| 1. Explore | Spawn Explore sub-agent; navigate organically; record friction | — |
| 2. Candidates | Synthesise friction into clusters; present max 8 with full context | — |
| 3. Pick | User selects a cluster and directs the angle | wait |
| 4. Frame | Problem statement, dependency category, blast radius, test boundary today | — |
| 5. Design | Spawn 3–4 parallel sub-agents with competing interface designs | — |
| 6. Choose | User picks interface or accepts recommendation | wait |
| 7. RFC file | Write arch-rfcs-YYYY-MM-DD.md to project root | — |
Full prompt text, cluster format, and step detail: see WORKFLOW.md.
Behavioural rules
- Explore agent friction observations are primary evidence — never override with static analysis
- Never propose interface designs before Step 5
- Never advance past Steps 3 or 6 without a user response
- Every RFC must include exact
file:line references and a before/after illustration
- Name every dependency category explicitly — it determines the testing strategy
- Rank clusters: testability impact first, then cognitive load, then interface stability
Advanced features
- Full workflow detail and Explore agent prompt:
${CLAUDE_SKILL_DIR}/references/WORKFLOW.md
- Friction vocabulary and dependency categories:
${CLAUDE_SKILL_DIR}/references/DETECTION-PATTERNS.md
- Sub-agent brief template and design constraints:
${CLAUDE_SKILL_DIR}/references/INTERFACE-DESIGN.md
- RFC action file format and complete example:
${CLAUDE_SKILL_DIR}/references/RFC-FILE-FORMAT.md
