review

Review one change set and return a decision-led report.

---

Guardrails

• Review branch changes against the selected base branch.
• Do not implement or modify code.
• Do not commit, merge, push, or delete branches.
• Block approval if the branch is behind the base branch; require sync + re-review.
• Do not update PRD tracking files here.
• Update tasks/context.md only 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. base branch/scope clarification), provide numbered short-reply options (e.g. 1, 2, 3).

---

Inputs

• base branch (default: repository default branch resolved from origin/HEAD; ask if unclear)
• optional PRD path (if scope validation is needed)

---

Workflow

1. Confirm base branch and scope target.
2. Collect context:
   • git fetch --all --prune to refresh remote state
   • git diff "<base>...HEAD"
   • git log "<base>..HEAD" --oneline
   • git status --short
3. Compare the change set against required behaviour:
   • If behind <base>, 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.
4. 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.
5. 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
6. Evaluate context-worthy review outcomes and update tasks/context.md inline 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