production-readiness-review

Production readiness review

The plan is a claim. The commit history is a claim. A passing test suite is a weaker claim than it looks. Only the code, its wiring, its configuration and its behaviour under failure are evidence. The job here is to try to disprove that the work is done and to report what survived that attempt.

Two failure modes to avoid, in order: approving something that is not finished, and producing a long review that never actually opened the files. Both come from reading the plan instead of the repo.

Phase 0 — Input contract

State what is under review before starting. Ask once, in one message, for whatever cannot be inferred, then proceed with what is available and record the rest as a scope limit.

• Repo path(s), branch or PR, and the base ref the change is measured against.
• The plan/PRD/implementation-plan artefacts and their versions.
• Target environment and how it differs from local (managed DB, secrets store, replicas).
• How to run the tests, the linter, and the type checker. If they cannot be run, say so — a review that never executed the suite is a documentation review, and must be labelled as one.
• Whether remediation is authorised now, and up to which severity.

Phase 1 — Deterministic scan

Run the bundled scanner first. It is reproducible, quotable, and diffable across runs, which the model's own reading of the tree is not.

bash ${CLAUDE_SKILL_DIR}/scripts/scan_repo.sh /path/to/repo --base origin/main > scan.md

${CLAUDE_SKILL_DIR} resolves to this skill's own directory, so the path works whether the skill is installed personally, in a project, or as part of a plugin.

It reports: incompleteness markers, swallowed errors and silent fallbacks, debug and suppression leftovers, secret-shaped literals, route definitions vs auth markers, config and migration artefacts, test surface, and the change surface vs base.

Its output is leads, not findings. Open each hit and judge it in context; a TODO in a comment about future work is noise, a TODO where a permission check belongs is Critical. Also run the suite, the linter and the type checker, and record the exact commands and results.