project-review

Project Review

Assess how a project is actually executing against its own plan — what's built, what's claimed, what's proven, and where the gaps are. The output is an honest, prioritized execution picture a decision-maker can act on, not a code-by-code critique. The discipline is separating "built" from "validated" from "planned" and refusing to let any of the three stand in for the others.

This is the execution lens. For vision, positioning, and market, run strategic-review; the two compose into a full pre-public / pre-milestone review (see templates/full-review-prompt.md).

Ground rule: cite or label

Every claim is either confirmed (cite the file/path/command output that proves it) or inferred (say so, and say from what). A reviewer who blurs the two is worse than no reviewer — the decision-maker can't tell evidence from optimism. Never report a capability as working unless you saw it work or saw a test that exercises it.

Step 1: Inventory the claims and the plan

Read the project's own statements of intent before judging anything:

• Scope & status claims — README, vision/strategy docs, roadmap, execution plan, CHANGELOG, milestone/issue tracker. What does the project say it is, what phase does it say it's in, and what does it promise for the milestone in question?
• The hard boundaries — declared scope and explicit non-goals. These are what you measure scope drift against.
• The working agreement — where the project says status lives and how milestones close. If "what's done" can't be answered from where it says, or there is no agreement, that is a finding: re-validate it with working-agreement.

Capture this as the baseline. Everything downstream is "reality vs this baseline." The report opens with it: a short list of what the project claims (scope, phase, milestone promises, headline numbers), each with its source, before any verdict. A bottom line that comes first has judged before the baseline exists. When the material was pasted in rather than readable, list it back from what was given. This is not a gate on delivering: write the baseline, then continue to Step 2 in the same response.

Step 2: Map implementation maturity

Walk the actual code/artifacts and classify each major component:

Tier	Meaning	Signals
Production-ready	Built, integrated, tested	Real implementation, callers, tests, in CI
Functional / thin	Works but unproven or partial	Implemented, light/no tests, edge cases open
Stub / scaffold	Shape exists, behavior doesn't	TODO, NotImplemented, empty handlers, returns mock data
Deferred / absent	Named in the plan, not started	Referenced in docs/roadmap, no code

Be specific: name the package/module/path and the tier. The deliverable is a maturity map, not a vibe. Grep for stub markers (TODO, FIXME, raise NotImplementedError, throw new Error("not implemented"), pass # stub).

Step 3: Reconcile against the roadmap — and find the drift

Lay the maturity map over the plan from Step 1:

• Ahead / behind — where is the code further along than the docs admit (common, and a sign the strategy doc is stale), and where is it behind a milestone it claims to have hit?
• Scope drift — what got built that isn't in scope? What's in scope but silently dropped? What crossed a declared non-goal boundary?
• Sequencing risk — is load-bearing work scheduled after the milestone that depends on it?

Step 4: Review the evidence it works

This is where most reviews are too generous. "The code is built" is not "the concept is validated." Assess the evidence chain:

• Tests — do they exist for the load-bearing paths, or only happy paths? Coverage numbers if available; quality, not just quantity.
• Validation / experimental results — if the project ran its own validation (efficacy data, benchmarks, A/B results, user trials), read the actual numbers and report what they say, including when they're negative or inconclusive. Foreground an uncomfortable result; don't bury it.
• CI / checks — does the pipeline actually gate, or is it advisory?
• The built-vs-validated gap — state it explicitly: which capabilities are built but unproven, and what evidence would close the gap?

Step 5: Prioritized execution findings

Produce ranked, severity-tagged findings, each tied to its evidence:

• Severity — Critical (blocks the milestone / claim is false) / High (material risk) / Medium (should fix) / Low (note it).
• Each finding: what, the evidence (cited), why it matters for the milestone, and the smallest action that addresses it.
• An execution scorecard — maturity, roadmap-adherence, evidence-strength, each rated with a one-line justification, so the reader gets the picture at a glance.
• Hand off the market half. When the review is for a launch, an announcement or going public, end the findings with one line naming strategic-review for vision, positioning and market, and do not answer those here, not even a suggested launch framing. The execution findings stay complete in this answer; only the market questions move.

Write the full report to a file — default a gitignored location (e.g. .local/project-review-<date>.md) unless told otherwise — and state its path in your final summary. This skill runs in a forked context: only the summary returns to the main conversation, so anything not written to disk is lost. If a judgment call needs user input (ambiguous scope boundary, missing baseline docs, which milestone to measure against), do not guess silently — record it in an Open questions section of the report and mention it in the summary.

For the rendered deliverable (interactive HTML report, dashboards, sortable findings table), hand off to artifact-design.

Principles Applied

• Honesty over comfort — a review that flatters the plan is worthless; lead the findings with the most load-bearing problem, even when it undercuts the project's thesis.
• Evidence over assertion — confirmed vs inferred, always; cite the source.
• Prioritize — a ranked short list of what matters beats an exhaustive catalog.
• Right altitude — execution health, not line-level nits (that's code-reviewing).

Cross-Skill References

• strategic-review — the other half of a pre-public review: vision, positioning, market.
• technical-debt-review — when the question is purely codebase health / remediation roadmap.
• code-reviewing — for a specific diff or PR, not a whole-project assessment.
• metrics-and-okrs — to turn findings into measurable readiness gates.
• artifact-design — to render the review as a polished interactive report.