Spec Peer Reviewer

Peer Reviewer

Objective

Deliver a high-signal peer review for planning artifacts before implementation starts. Prioritize defects and execution risks, not writing style.

Inputs

Provide:

1. Target document path(s) to review.
2. Optional related references (code, schema, migration files, linked docs).
3. Optional review focus (for example: data contracts, testability, rollout risk).

Workflow

1. Read the target doc end-to-end and build a requirement map:

   • goals, non-goals, acceptance criteria, dependencies, constraints, open questions.

2. Cross-check internal consistency:

   • detect contradictions between goals, acceptance criteria, and technical approach.

3. Validate feasibility against implementation reality:

   • compare required behavior with existing CLI, contracts, DB schema, and test patterns.

4. Run risk lenses:

   • scope boundaries, backward compatibility, data integrity, observability, testability, delivery sequencing, migration/deletion safety.

5. Produce findings ranked by severity with concrete remediation and PRD/plan update instructions.

Severity Rubric

Use exactly these labels:

1. critical: Release-blocking contradiction or missing requirement that can cause wrong behavior, data loss/corruption, severe security/compliance risk, or invalid scope.
2. major: High-impact gap likely to cause rework, failed delivery, or materially incorrect/ambiguous implementation.
3. normal: Important clarity/testability/operability issue that should be fixed for reliable execution but is not release-blocking.
4. low: Improvement for precision, maintainability, or readability with limited delivery risk.

Review Lenses

Use all lenses, then emphasize the highest-risk areas:

1. Problem framing: Is the problem measurable and tied to user/business outcomes?
2. Scope boundaries: Are non-goals explicit and enforceable?
3. Requirements quality: Are acceptance criteria verifiable, unambiguous, and complete?
4. Data/contracts: Are schemas, stage identities, keys, and invariants defined correctly?
5. Failure behavior: Are error handling, edge cases, and exit semantics explicit?
6. Compatibility/migration: Are deletion and replacement plans gated and reversible?
7. Testing strategy: Are test gates realistic, sufficient, and aligned to risk?
8. Operational readiness: Are observability, metrics, and rollout safeguards specified?
9. Sequencing: Is implementation order coherent and dependency-safe?

Output Format

Produce findings first, sorted by severity descending. Include:

1. Severity
2. Issue
3. Evidence with file path and line reference
4. Recommendation
5. How to update PRD/plan with section-level patch guidance

Then include:

1. Open questions/assumptions (only if unresolved decisions remain)
2. Optional short summary (after findings)

If no findings exist, state that explicitly and list residual risks or testing gaps.

PRD Update Guidance Pattern

For each finding, propose document edits that are directly actionable:

1. section to modify (for example: "US-003 Acceptance Criteria")
2. exact change type (add, replace, clarify, defer, gate)
3. specific text direction (what requirement to add/change and why)

Implementation Plan Add-On

When reviewing implementation plans, additionally verify:

1. each increment is atomic and independently testable
2. each increment has a deterministic test gate
3. dependency ordering is explicit
4. rollback/remediation paths exist for risky increments
5. file ownership and touch-points are scoped to reduce regression risk

Ralph Loop Readiness

When reviewing plans intended for autonomous execution via ralph-loop-runner, additionally verify:

1. Every increment has a **Status:** pending field.
2. The plan header includes **Overall Status:** and **Current Increment:** fields.
3. The milestone table includes a Status column.
4. Test gates contain executable commands (not prose descriptions).
5. The corresponding PRD has - [ ] checkboxes on all acceptance criteria.
6. The PRD has **Status:** fields on each user story.
7. Increments are ordered so that each can be implemented independently of later ones.

If any of these are missing, flag as major severity — the plan cannot be executed autonomously without them.

Do not implement code in this skill; review and planning quality is the deliverable.