sanurb/explore-architecture

Explore Architecture

Use codemogger semantic/keyword search and git co-change analysis to find architectural friction. Output a numbered list of deepening candidates with quantitative evidence.

A deep module (Ousterhout) has a small interface hiding a large implementation. This skill finds shallow modules that should be deepened.

Instructions

Step 1. Gather quantitative signals

Run the co-change analysis script against the target repo:

bash <skill-dir>/scripts/co-change-analysis.sh <path-to-repo>

Then run targeted codemogger searches to detect coupling patterns:

npx codemogger search "shared types imported across modules"
npx codemogger search "wrapper adapter delegate"
npx codemogger search "interface implementation"

Use keyword mode for precise identifier lookups when you spot a suspicious type or function:

npx codemogger search "TypeName" --mode keyword

If zoekt is indexed, use it for regex and boolean queries:

zoekt 'sym:InterfaceName' 
zoekt 'file:test -file:fixture error handling'

Step 2. Classify friction

For each friction signal found, cross-reference co-change data with search results. Look for:

• Modules whose interface is nearly as complex as the implementation (shallow)
• Files that always change together but live in separate modules (coupling)
• Pure functions extracted "for testability" where real bugs live in call-site integration
• Adapter/wrapper layers that pass through without adding depth
• Shared types imported by many modules (hidden coupling)
• Untested or brittle test boundaries

Classify each candidate's dependency category using the decision tree:

I/O involved?
├─ No → in-process (merge directly)
└─ Yes
    ├─ Local stand-in exists? → local-substitutable
    └─ No
        ├─ You own the service? → ports-adapters
        └─ No → mock-boundary

Step 3. Present candidates

Output the candidate list in the exact format specified below. Do NOT propose interfaces — only list candidates. Ask which to explore.

Non-Negotiable

• Must run co-change script before presenting candidates.
• Each candidate must have quantitative coupling evidence (co-change frequency OR cross-reference count from codemogger).
• Each candidate must be classified into exactly one dependency category.
• Must NOT propose interfaces or solutions — output is candidates only.
• Must use codemogger search results as evidence, not just the agent's intuition.

Output

## Deepening Candidates

### 1. [Cluster name]
- **Modules**: `path/to/a`, `path/to/b`
- **Coupling**: [shared types | co-change N times | M cross-references]
- **Category**: [in-process | local-substitutable | ports-adapters | mock-boundary]
- **Test impact**: [which tests become redundant at boundary]
- **Depth gain**: [interface surface shrink vs implementation absorbed]

### 2. [Cluster name]
...

Which candidate would you like to explore?

Scripts

| Script | Purpose | |--------|---------| | scripts/co-change-analysis.sh | Detect files that frequently change together via git history |