architect

name	architect
description	Find deepening opportunities in a codebase — refactors that turn shallow modules into deep ones. Use when the codebase feels hard to change, bugs cluster in certain modules, adding features requires touching many files, or proactively every few days as a health check.
argument-hint	[module or area to improve, or 'full scan']

Improve Codebase Architecture

"Programs must be written for people to read, and only incidentally for machines to execute." — SICP

Philosophy

Codebases naturally decay into "balls of mud." This skill combats that by finding deepening opportunities — small, targeted investments in design quality that pay compound dividends. See LANGUAGE.md for the precise terminology used throughout.

Glossary

Use these terms exactly. Consistent language is the point.

• Module — anything with an interface and an implementation (function, class, package, slice)
• Interface — everything a caller must know to use the module: types, invariants, error modes
• Implementation — the code inside
• Depth — leverage at the interface: a lot of behaviour behind a small interface. Deep = high leverage. Shallow = interface nearly as complex as implementation
• Seam — where an interface lives; a place behaviour can be altered without editing in place
• Adapter — a concrete thing satisfying an interface at a seam
• Leverage — ratio of behaviour provided to interface surface area

Workflow

Copy this checklist and track your progress:

Architecture Review Progress:
- [ ] Step 1: Map module boundaries
- [ ] Step 2: Assess each module
- [ ] Step 3: Identify deepening opportunities
- [ ] Step 4: Prioritize and propose
- [ ] Step 5: Execute with TDD

Step 1: Map Module Boundaries

Using CONTEXT.md as guide, list major modules and their stated responsibilities.

Step 2: Assess Each Module

For each module, evaluate:

Criterion	Question
Cohesion	Do all functions serve a single purpose?
Coupling	How many modules depend on this? How many does it depend on?
Clarity	Can you explain it in one sentence?
Testability	Can it be tested in isolation?
Depth	Is the interface simpler than the implementation?

Step 3: Identify Deepening Opportunities

Look for:

• Shallow modules — Interface as complex as implementation → merge or deepen
• Shotgun surgery — One change touches many files → consolidate
• Feature envy — Module A uses Module B's data more than its own → move behavior
• Dead code — Unused exports → remove
• Missing seams — Hard-coded dependencies → extract interface + adapter

Step 4: Prioritize and Propose

For each opportunity, assess:

• Impact — How much friction does this cause? (High/Med/Low)
• Effort — How much work to fix? (High/Med/Low)
• Risk — What could go wrong?

Prioritize: High impact, Low effort first. Never propose big-bang rewrites.

Step 5: Execute with TDD

For each approved change:

1. Write tests for the affected module (if not already covered)
2. Make the change incrementally
3. Run tests after each step
4. Update CONTEXT.md and create ADR in docs/adr/

Anti-Patterns

• Big bang rewrites — Incremental improvement is always safer
• Architecture astronautics — Every abstraction must solve a concrete problem
• Premature generalization — Design for today, accommodate tomorrow
• Gold-plating — Simple and working beats elegant and broken

Integration

• Use /zoom-out before /architect for full system context
• Use /tdd during /architect to safely execute changes
• Use /to-issues to break improvements into grabbable tasks
• Use /grill to align with team on proposed changes