| name | project-review |
| description | Use when auditing a repository's overall health, tech debt, maintainability, or architecture quality; processing a third-party repo-wide audit; or exhaustively reconciling OpenSpec specs against implementation. Triggers include "review this project", "audit the codebase", "assess project health", "does code match the spec", and "reconcile spec vs implementation" — not single-PR review or backlog prioritization. |
| metadata | {"owner":"tze","authors":["tze","Claude Fable 5","Claude Sonnet 4.6","OpenAI Codex"],"status":"active","last_reviewed":"2026-07-13"} |
Project Review
Blunt, evidence-based audit of a repo across 15 categories. Establish the normative baseline via /project-shape first; hand confirmed findings to /project-direction for scheduling. README is a claim to validate, not primary truth when shape artifacts exist.
Sample triggers: "review this project" · "audit the codebase" · "assess project health" · "process this third-party review" · "reconcile spec vs implementation".
Not for: single-PR/diff review (use /th-engineering), or deciding what to build next (use /project-direction).
Normative source order: 1. about/heart-and-soul/ + about/legends-and-lore/ → 2. openspec/ → 3. about/lay-and-land/ → 4. README/docs/issues → 5. inference from code+history.
Every major claim cites specific files/sections. Label assertions [Observed] / [Inferred] / [Unknown]. Every criticism carries a concrete remedy.
Workflow
Phase 0 — Normative baseline via /project-shape
Run project-shape's scanner directly; load its maturity rubric only when
interpreting the score. Do not load the full sibling skill for this baseline:
bash ../project-shape/scripts/shape-scan.sh <repo_root>
Classify each pillar on project-shape's per-pillar scale: absent / nascent / structured / mature. The scan's Assessment line uses a separate five-level repo rubric (Unshaped/Nascent/Structured/Shaped/Mature — see ../project-shape/references/maturity-rubric.md); report both, never conflate pillar ratings with repo assessment.
Baseline rules:
- Pillars
structured/mature → primary normative baseline for their domains. Read the actual doctrine/design/spec/topology/craft-and-care files before reviewing code; extract non-negotiables, scope boundaries, architectural claims, normative requirements; note contradictions between pillars without silently resolving them.
- Some pillars present → use those normatively, fall back elsewhere.
- All
absent/unusable, or shape weak/missing → fall back to README/docs/code as provisional truth, lower confidence on alignment + product-coherence + roadmap judgments, and flag the absence of normative artifacts as a project risk.
Phase 0 output — baseline packet: per-pillar maturity + missing pillars · source-of-truth order used · explicit doctrine/spec requirements code must satisfy + craft-and-care execution standards · unresolved contradictions across doctrine/lore/spec/README/code.
Phase 1 — Automated repo scan
bash scripts/project-scan.sh <repo_root>
Then read references/project-type-adaptations.md to calibrate scoring by project type and maturity.
Calibration rule: project-shape sets normative requirements; project-type-adaptations.md adjusts emphasis. On conflict, shaped project artifacts win.
Edge cases:
| Situation | Handling |
|---|
| <50 source files | Skip subagent fan-out; single-agent review OK |
| >50k LOC | Focus entry points, churn hotspots, public API, normative requirements |
| Monorepo, 10+ packages | Sample 3-5 representative packages + shared/core |
| No README/docs | Infer goals from git history, tests, manifests, comments |
| Shallow clone | Note in report; commit/churn data unreliable |
| Generated code (protobuf, ORM, bundles) | Exclude from quality scoring; note presence |
| Shape absent/weak | Treat missing pillars as maintainability + planning risk, not just doc gap |
Phase 2 — Parallel investigation
Read references/investigation-guides.md (per-domain checklists) and references/subagent-template.md (dispatch format).
Dispatch plan:
| Agent | Domain | Scores | Key focus |
|---|
| A | Mapping & baseline reconciliation | — | Repo map, goals, doc + shape-vs-code contradictions |
| B | Code quality & architecture | 1-4 | Modularity, clarity, correctness, normative violations |
| C | Reliability & tooling | 5-8 | Errors, observability, testing, hygiene |
| D | Security, perf & data | 9-12 | Dependencies, auth, performance, API/data design |
| E | Docs, ops & maintainability | 13-15 | Documentation, release, change safety, missing shape artifacts |
| F | Gaps, scale & planning constraints | — | Feature gaps, 10x/100x, risk register, sequencing constraints |
Strategy:
- Launch A-F in parallel for a full review.
- Pass artifact paths plus a compact Phase 0 manifest and scoped scan excerpt;
do not paste the same full baseline/scan into every prompt. Assign one primary
evidence owner per concern so overlapping domains cite rather than rescan.
- Change-level quality bars live in
/th-engineering subskills — B: code-readability + dependency-hygiene; C: test-rigor (+ diagnosis for flake/root-cause evidence); E: documentation. When craft-and-care is absent/silent on a domain, agents cite those bars rather than inventing criteria; investigation-guides.md stays the evidence checklist, not a second bar.
- Human-facing surfaces load
/th-design only for implicated experience
concerns (design-bar by default; accessibility, discoverability,
information-design, interaction-speed, or visual-language when specific).
Backend-only scopes do not pay this context cost.
- Agent F's roadmap draft is advisory only — no beads, no scheduling.
Each subagent receives: Phase 0 baseline packet · shape-scan output · project-scan output · project context (type/users/maturity/scope) · its domain section from investigation-guides.md · relevant rubric sections from references/scoring-rubric.md · relevant calibration from project-type-adaptations.md.
Phase 3 — Synthesis
Collect subagent reports. Read references/report-template.md for output structure.
- Merge scores conservatively — on disagreement take the lower score, record the disagreement.
- Mark genuinely inapplicable categories
N/A; exclude from average.
- Bucket findings: Normative violations (doctrine/lore/spec/topology contradicted by code) · Generic health risks (quality/reliability/tooling/security/perf/DX) · Shape gaps (missing/stale pillars weakening confidence) · Deprioritized (good ideas that don't fit context).
- Build risk register by severity × likelihood.
- Generate advisory roadmap (quick wins / medium / strategic) — synthesis only, creates no execution artifacts.
- Assign verdict:
| Verdict | Criteria |
|---|
| Healthy | No category <3; no critical risks; avg ≥3.5 |
| Healthy but fragile | No category <2; ≤1 critical risk; avg ≥3.0; but missing safety nets |
| Functional but accumulating debt | 1-3 categories <3; avg 2.5-3.5; growing risk register |
| At risk | 3+ categories <3 OR any at 1 OR 2+ critical risks; avg <3.0 |
| Severely at risk | 5+ categories <3 OR multiple at 1 OR critical security/data risks; avg <2.0 |
- Prepare
/project-direction handoff packet: confirmed findings only · Phase 0 baseline packet · required doctrine/lore/spec updates before planning · sequencing constraints + dependency hints · deprioritized items with reasons · evidence index. Write it to docs/reviews/YYYY-MM-DD-{scope}-packet.md with the reviewed commit SHA on the first line — that file is the cross-session handoff contract project-direction's receiver protocol reads; a packet living only in conversation dies with the session.
Phase 3.5 — Veracity Gate
Before delivering the report, challenge every Critical/High/P0/P1 finding and the top roadmap items. Read references/review-veracity-gate.md for the full procedure.
For each claim:
- Re-open the named file/path directly.
- Search for contradictory evidence using exact terms from the claim.
- Verify referenced paths exist.
- Verify process claims against actual SKILL/docs/scripts/config.
- Classify:
[Confirmed] · [Overstated] · [Incorrect] · [Unverifiable].
- Delete or demote anything not
[Confirmed].
- Append invalidated claims to the Veracity Ledger (Appendix D in
report-template.md); exclude them from the risk register and roadmap.
Special rule: Formatting, line-length, and script-invocation claims require local-checkout evidence or GitHub-blob evidence. Raw/parser rendering alone is not sufficient — mark such claims [Unverifiable] unless you have blob-level proof.
Any P0/P1 recommendation that survives must cite both supporting evidence and the contradictory evidence checked.
Phase 4 — Deliver
Output the report per report-template.md. Make the boundary explicit: project-review audits and classifies; project-direction decides sequencing, specs, and beads.
Adapting to scope
- Full review (default): all 6 subagents, all 15 categories, complete report + handoff packet.
- Focused review (user names categories): dispatch only relevant subagents. Still include normative baseline, scorecard for scoped categories, risk register, handoff packet.
- Quick health check (fast answer): shape scan + project scan + Agent A, then a brief orchestrator sweep of obvious high-risk areas (tests, CI, auth/secrets, docs). Output: exec summary, provisional scorecard, top 5 risks, explicit low-confidence markers. Don't pass this off as a full review.
- Third-party deep-dive ("process this review/audit"): fact-check external findings, filter through actual context, convert confirmed findings into a handoff packet, route planning to
/project-direction. Read references/third-party-review.md for the five-step protocol.
- Spec reconciliation ("reconcile spec vs implementation", "what's implemented but undocumented", "what's specified but missing"): exhaustive bidirectional spec↔code mapping, report-only by default. Remediation requires explicit authorization; then observed behavior gets spec bookkeeping, cohesive unimplemented outcomes get beads, and strategic gaps escalate to
/project-direction. Read references/spec-reconciliation.md. Samples nothing.
Anti-patterns
- Skipping
/project-shape, treating README as sufficient when doctrine/spec artifacts exist
- Accepting external-review severities at face value
- Treating all recommendations as equally important
- Enterprise-framing a personal project
- Creating beads/execution artifacts from
project-review (scoped exception: spec-reconciliation remediation)
- Preserving the review as canon instead of extracting durable doctrine/spec/planning updates
References
| File | Read when | Answers |
|---|
../project-shape/references/maturity-rubric.md | Phase 0 score interpretation | Conservative per-pillar/repo maturity rules; load only when the scanner result needs interpretation |
../project-direction/SKILL.md | Phase 3-4 | Planning contract, sequencing expectations, handoff target |
references/scoring-rubric.md | Phase 2 | 1-5 criteria per category with evidence guidance |
references/investigation-guides.md | Phase 2 | Per-domain checklists, search patterns, deliverables |
references/subagent-template.md | Phase 2 | Dispatch template and required prompt fields |
references/report-template.md | Phase 3-4 | Output structure, scorecard, handoff packet layout |
references/project-type-adaptations.md | Phase 1-3 | Category weighting by project type, maturity expectations, hybrid handling |
references/spec-reconciliation.md | Spec reconciliation mode | Bidirectional spec↔code inventory, coverage table, gap analysis, remediation |
references/third-party-review.md | Processing an external review/audit | Fact-check, context-filter, ROI tiers, planning-input prep, episodic-artifact handling |
references/review-veracity-gate.md | Phase 3.5 | Full gate procedure: per-claim verification steps, classification rules, Veracity Ledger format, special evidence rules |
../../references/spec-format.md | Writing/extending specs during reconciliation | OpenSpec file format: heading hierarchy, WHEN/THEN rules, naming (shared contract) |
Scripts
After review: schedule with /project-direction
Once findings are confirmed, invoke /project-direction with the Phase 3 handoff packet at docs/reviews/ (Phase 0 baseline packet, not just the scorecard). Ownership stays separate: project-review audits, /project-direction plans.
