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.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. 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

1. 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.
2. 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
3. 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.
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