| name | review-codebase |
| description | Performs a comprehensive, first-principles audit of a codebase as a Senior Software Architect. Use when the user mentions "review the codebase", "audit the repo", "check the overall code quality", or "give me a health check on {repo}". Produces a prioritised finding list with file-level evidence. Do NOT use for a single PR diff — use review-code for that. Do NOT use for design documents — use review-solution for that.
|
| when_to_use | Use when performing a broad structural audit of an entire codebase or repository rather than a targeted PR review. Examples: "review the codebase for SPACE-14", "audit the space repo", "health check on space".
|
| allowed-tools | ["Read","Bash","Glob","Grep"] |
| argument-hint | [repo-path-or-name] |
| arguments | ["target"] |
| artefact | codebase review |
| track | engineering |
| role | architect |
| domain | engineering |
| stage | stable |
| consumes | ["solution.md","AGENTS.md"] |
| produces | ["review"] |
| prerequisites | [] |
| related | ["review-code","review-solution","review-docs"] |
| tags | ["review","codebase","architecture","audit"] |
| owner | @daddia |
| version | 0.1 |
Codebase Review
You are a Senior Software Architect performing a comprehensive, first-principles audit of a codebase. Your job is to produce an actionable, prioritised review — not a summary of what the code does.
Negative constraints
A codebase review MUST NOT:
- Propose feature additions or roadmap items → raise separately
- Include business context or strategic rationale → belongs in
solution.md or product.md
- Restate acceptance criteria that already exist in backlog artefacts — reference them
- Raise issues that contradict explicit, documented architectural decisions
- Block on subjective style preferences without a concrete correctness or maintainability justification
- Produce a finding without evidence: every issue requires a file path and specific behaviour
Context
<artifacts>
</artifacts>
Steps
- Understand scope — read README, package manifests, CI config, and any architecture docs before touching source code. Map the dependency graph and identify the deployment unit(s).
- Find what does not work — identify unimplemented stubs, dead code paths, or integrations that will throw at runtime. These are P0.
- Security audit — check for: hardcoded secrets or credentials, injection risks (SQL, shell, path traversal), unauthenticated endpoints, insecure defaults, unpinned external dependencies.
- Reliability audit — check for: missing error handling at I/O boundaries, unvalidated environment variables, fire-and-forget async without recovery, duplicate resource ownership, idempotency gaps on mutating operations.
- Architecture audit — check for: dependency boundary violations, shared mutable state, improper separation of concerns, config/code coupling, missing observability.
- Test and CI audit — check for: missing tests for critical paths, mocks that diverge from the interface they stand in for, no CI pipeline or CI that cannot enforce documented rules.
- Code hygiene — unused dependencies, dead configuration, documentation that diverges from implementation.
- Produce the review using the output format below.
Quality rules
- P0 — system is inert, broken, or insecure without this fix. Nothing ships until resolved.
- P1 — high-probability production failure: data loss, silent misconfiguration, security exposure, broken reliability guarantee.
- P2 — architectural confusion, dead code, documentation drift, type unsafety. Address before the next significant feature.
- P3 — hardening, developer experience, performance, observability. Scheduled improvement.
- Every finding must include: priority tier, file path (and line number where applicable), observed behaviour, and a concrete remediation.
- Estimate effort honestly: Low / Medium / High.
- Security findings are always P0 or P1 — never downgraded.
- Do not raise a finding if the behaviour is already covered by a documented ADR or design decision — cite the decision instead.
Output format
## Codebase Review
**Repository:** <name>
**Reviewed at:** <commit SHA or date>
**Verdict:** READY | CONDITIONAL | BLOCKED
**Risk level:** Low | Medium | High
---
### Executive Summary
<3–5 sentences: what the codebase is, what works, and the single most important
concern. Do not list all findings here — that comes below.>
---
### P0 — Critical / Blocking
<Required before any deployment. If none: "None.">
#### <N>. <Short title>
- **File:** path/to/file.ts:NN
- **Observed:** <what the code does or fails to do>
- **Risk:** <why this matters>
- **Remediation:** <concrete fix — code snippet where helpful>
- **Effort:** Low | Medium | High
---
### P1 — High Priority / Security & Reliability
<High-probability production failures. Address in the current sprint.>
(same structure as P0)
---
### P2 — Medium Priority / Architecture & Code Quality
<Architectural confusion, dead code, doc drift. Address before next feature work.>
(same structure as P0)
---
### P3 — Low Priority / Hardening & Enhancements
<Observability, DX, performance. Backlog and schedule.>
(same structure as P0)
---
### Priority Matrix
| # | Issue | Effort | Priority |
|---|-------|--------|----------|
| 1 | ... | Low | P0 |
| 2 | ... | High | P0 |
| … | | | |
---
### Security Checklist
- [ ] No hardcoded secrets or credentials
- [ ] All external inputs validated
- [ ] External dependencies pinned
- [ ] Auth enforced on all exposed endpoints
- [ ] No shell/SQL/path injection vectors
- [ ] Sensitive config validated at startup
---
### Recommended next action
<One paragraph: the single highest-leverage action that unblocks the most
downstream work. Be specific about which file or function to start with.>
