review
Review one change set and return a decision-led report.
Guardrails
- Review changes made on the currently checked-out branch.
- Do not implement or modify code.
- Do not commit, merge, push, or delete branches.
- Do not ask the user which branch to check against.
- Resolve the comparison base automatically from the repository default/base branch.
- Block approval if the current branch is behind the resolved comparison base; require sync + re-review.
- Do not update PRD tracking files here.
- Update
tasks/context.mdonly for durable review outcomes. - Examples: recurring risks, release-critical gotchas, or confirmed follow-up decisions.
- Do not invent test results; run checks or call out missing evidence.
- When asking for user decisions (e.g. scope clarification), provide numbered short-reply options (e.g.
1,2,3).
Inputs
- current branch (resolved from
git branch --show-current) - comparison base (default/base branch resolved automatically; do not prompt for it)
- optional PRD path (if scope validation is needed)
Workflow
- Resolve current branch and comparison base automatically.
- Prefer the repository default branch resolved from origin/HEAD. - Otherwise use the local default branch (main, master, or dev) when exactly one exists. - If the comparison base cannot be resolved, return Good to commit: No with the exact commands/data needed to resolve it.
- Collect context:
- git fetch --all --prune to refresh remote state - git diff "<comparison-base>...HEAD" - git log "<comparison-base>..HEAD" --oneline - git merge-base --is-ancestor "<comparison-base>" HEAD - git diff --staged - git diff - git status --short
- Compare the change set against required behaviour:
- If git merge-base --is-ancestor "<comparison-base>" HEAD fails, return Good to commit: No and require sync before re-review. - correctness and edge cases - security risks and data handling - test depth and regression risk - scope control (especially if PRD path is provided) - Compare diff vs PRD 'In scope' and completed user stories; flag any diff not attributable to a PRD requirement.
- Classify findings:
- blockers (must fix) - suggestions (optional improvements) - missing evidence (tests/checks not run, unclear behaviour) - If unable to run checks (CI-only, permissions), mark as "Missing evidence". - Request a specific artifact: CI link, log, or command the user can run.
- Produce the report with a clear recommendation:
- Good to commit: Yes or Good to commit: No - if decision is No, include explicit fix items and ask the user to address them before rerunning review
- Evaluate context-worthy review outcomes and update
tasks/context.mdinline when needed:
- systemic risks likely to recur - key security or data-handling decisions - durable follow-up decisions that affect future work - if no durable outcome exists, mark context as skipped with reason in the report
Review Checklist
- Correctness:
- empty/null/error paths - boundary values and state transitions - ordering/concurrency/time assumptions (if applicable)
- Security:
- authn/authz behaviour - input validation and output encoding - secret/PII handling and logging safety - dependency risk for newly introduced packages
- Tests and verification:
- happy path + key failure paths - regression coverage in touched areas - manual verification steps when automation is missing
- Maintainability:
- naming clarity and control-flow simplicity - comments/docs for non-obvious decisions only
References
references/report-template.md: standard report structure for review outputs.
Output
- Return the review report with explicit context update status.
- Keep the decision explicit and unambiguous.
- End with a short status block:
- Files changed: list of created/updated files - Key decisions: any assumptions or choices made (if any) - Next step: recommended next skill or action