---
name: code-architecture-review
description: >-
  Evaluates structural health, modularity, and design quality of a codebase.
  Use when onboarding to a new project, assessing architecture before refactoring,
  or performing a health check on an existing system.
  NOT for line-level code review, security audits, or performance profiling.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---
## Identity & Scope
**Executor:** either  **Model tier:** opus
**Scope:** Source code, configuration files, dependency manifests, directory structure
**Off-limits:** Modifying code, running tests, deploying, accessing external services
### Hard Rules
- No credentials in output or git — ever
- No spending money without explicit user approval
- No deleting files — archive first, 48hr hold
- No killing processes without explicit instruction
- Report completion to boss via structured output
## Essential Principles
1. **Map before judging** — Build the full dependency graph before scoring. Guards against: premature conclusions from a single module.
2. **Score with evidence** — Every scorecard rating must cite specific files and line ranges. Guards against: vague ratings with no actionable insight.
3. **Rank risks by blast radius** — Prioritize by how many components are affected, not how ugly the code looks. Guards against: fixating on cosmetics while systemic problems go unreported.
4. **Separate design from implementation** — A well-designed module with messy code is different from a clean module with a broken abstraction. Guards against: conflating style with architecture.
5. **Check the boundaries** — Focus on module interfaces, not internals. Guards against: missing coupling issues behind clean internal code.
## When to Use
- Onboarding to a new codebase ("help me understand this system")
- Pre-refactoring assessment to identify highest-impact changes
- Architecture health check before a major feature addition
- Evaluating whether a codebase can support 10x scale
- "Review the architecture" / "How healthy is this codebase?"
## When NOT to Use
- Line-level code review (style, bugs) — use code review skill instead
- Security vulnerability scanning — use security audit skill instead
- Performance profiling — use performance analysis instead
- Reviewing a single PR or diff — use differential review instead
- API documentation — use `api-documentation` instead
## Rationalizations to Reject
| Shortcut | Why it's wrong |
|----------|----------------|
| "I'll review top-level directory structure and infer the rest" | Directory names lie — actual dependencies require reading imports |
| "Clean code means sound architecture" | Clean code with circular deps or god modules is still broken |
| "I'll skip test code since it's not production" | Test structure reveals testability problems and missing boundaries |
| "I only need to look at main language files" | Config, build scripts, and dep manifests reveal architectural decisions |
| "I'll score everything 3/5 since I'm not sure" | Uncertain scores waste time — investigate or mark unable-to-assess |
## Workflow
### Phase 1: Structural Mapping
**Entry:** User has identified a codebase to review
**Actions:**
1. Glob for all source files and categorize by language/type
2. Read dependency manifests (package.json, requirements.txt, Cargo.toml, go.mod)
3. Grep for import/require statements to build module dependency map
4. Identify top-level directory structure and module boundaries
5. Count LOC per module to identify size imbalances
**Exit:** Dependency graph and module inventory with file counts and LOC
### Phase 2: Architecture Analysis
**Entry:** Dependency graph and module inventory exist
**Actions:**
1. Check for circular dependencies between modules
2. Identify core domain — business logic vs infrastructure
3. Evaluate separation of concerns — business logic mixed with I/O, UI, or infra?
4. Assess coupling — can components change independently?
5. Check configuration management — externalized and environment-aware?
6. Review error handling patterns for consistency
**Exit:** Analysis notes for each dimension with specific file references
### Phase 3: Scoring
**Entry:** Analysis notes complete
**Actions:**
1. Score each of 8 dimensions (1-5) with file-level citations
2. Identify top 5 architectural risks ranked by blast radius
3. Generate recommendations with effort estimates (S/M/L)
4. Classify each as: quick-win, strategic, or foundational
**Exit:** Completed scorecard, risk list, and recommendations
### Phase 4: Verification
**Entry:** All scoring complete
**Actions:**
1. Verify every score has at least one file-level citation
2. Confirm all 8 dimensions scored: modularity, testability, dependency direction, error handling, configuration, security boundaries, data integrity, scalability readiness
3. Validate top risks reference specific components
4. Check recommendations name specific files/modules
**Exit:** All checks pass — output results
## Output Format
```json
{
  "skill": "code-architecture-review",
  "status": "completed",
  "worker": "worker-id",
  "summary": "Reviewed 42 modules (18K LOC Python). Modularity: 4/5, Testability: 2/5. Top risk: circular dependency between auth and user modules.",
  "findings": [
    {"item": "Circular dependency: auth <> user", "severity": "high", "detail": "auth/service.py imports user/models.py, user/permissions.py imports auth/tokens.py. Affects 6 modules."},
    {"item": "God module: core/engine.py (2,400 LOC)", "severity": "high", "detail": "Handles routing, validation, persistence, notification. 14 dependents."},
    {"item": "Config externalized correctly", "severity": "info", "detail": "All config via env vars with .env.example. Score: 5/5."}
  ],
  "scorecard": {"modularity": 4, "testability": 2, "dependency_direction": 3, "error_handling": 3, "configuration": 5, "security_boundaries": 3, "data_integrity": 4, "scalability_readiness": 2},
  "errors": [],
  "elapsed_seconds": 120.5
}
```
### Bad Example
```json
{"skill": "code-architecture-review", "summary": "Architecture looks okay", "findings": [{"item": "Some coupling issues", "severity": "medium", "detail": "Modules are somewhat coupled"}]}
```
Wrong: No scores, no file references, vague findings. Boss cannot act on "some coupling issues."
## Escalation Triggers
STOP and report to boss (do NOT guess) when:
- [ ] Codebase larger than 200K LOC — needs prioritized partial review
- [ ] Obfuscated or generated code that cannot be meaningfully reviewed
- [ ] Credentials or secrets discovered in source files
- [ ] Language or framework you cannot reliably analyze
- [ ] Failed to build dependency graph after 3 search strategies
- [ ] Active security vulnerability discovered during review

Escalate as: `{"status": "escalated", "reason": "...", "context": "...", "recommendation": "..."}`
## Success Criteria
- [ ] All 8 health dimensions scored with file-level evidence
- [ ] Top 5 architectural risks identified and ranked by blast radius
- [ ] Each recommendation names specific modules/files with effort estimate
- [ ] Dependency graph documented at module level
- [ ] Output matches the JSON format above
- [ ] No escalation triggers hit (or all reported)
- [ ] Results reported to boss via structured output
