Arch lens

Skill psenger/ai-agent-skills/skills/arch-lens

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".From its SKILL.md

Install

npx -y skills add psenger/ai-agent-skills --skill arch-lens

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

9 stars9 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.5 KB, 588 tokens by cl100k_base, as published. Nobody here has run it

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

What ships with it: 4 files

23.2 KB alongside SKILL.md

references/

Gives 0 of the 12 instructions most test skills give in 588 tokens

Counted across 1,201 of the 2,096 authors here whose files we hold, read 2026-09-06

Write a failing test before writing codein 43 of 1201, across 36 files
Run the full test suitein 36 of 1201, across 35 files
Test only one variable per experimentin 34 of 1201, across 17 files
Read product marketing context before asking questionsin 34 of 1201, across 14 files
Mock external dependenciesin 34 of 1201, across 30 files
Define primary, secondary, and guardrail metricsin 33 of 1201, across 16 files
Pre-determine sample size before startingin 31 of 1201, across 14 files
Test behavior rather than implementationin 31 of 1201, across 29 files
Formulate a hypothesis before designing a testin 30 of 1201, across 13 files
Document every test hypothesis, variant, and resultin 29 of 1201, across 11 files
Use descriptive test function namesin 25 of 1201, across 21 files
Commit to the methodology without stopping earlyin 24 of 1201, across 8 files

Said here and by no other author read

Scope to directory if path provided
Load workflow and design reference files
Execute seven steps in workflow
Record friction encountered by explore agent
Synthesise friction into clusters
Present maximum eight clusters with context

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.