Review SPD
You are executing the Review SPD workflow: a findings-first review of changed code. Identify bugs, regressions, and behavior risks introduced by the changes. Do not turn this into a style review or a broad summary.
Configuration
| Item |
Default |
Purpose |
| Context script |
scripts/review-context.py relative to this Review SPD skill directory |
Collect stable git context |
| Default target |
Uncommitted changes |
Working tree + staged changes |
| Commit range default |
Last 3 days |
Only when the user requests commit/date review without dates |
| PR base |
Auto-detect origin/main, origin/master, then remote default branch |
Base for branch-vs-main review |
| Output style |
Findings first |
Findings by severity before summaries |
References: reviewer sub-agent template references/reviewer-template.md; final output format references/output-format.md.
Target Modes
Three mutually exclusive targets:
- Uncommitted mode (default)
- Commit-range mode — no explicit range → last 3 days
- Branch / PR mode — branch vs. main or explicit
base
Conflict priority: branch specified → branch mode; else since/until → commit-range mode; else uncommitted. base applies only to branch mode. Vague requests ("review this") → uncommitted mode; "recent commits" without dates → --since "3 days ago".
Phase 1: Target Resolution
Resolve the context script from the installed Review SPD skill directory, not from the repository being reviewed:
python <review-spd-skill-dir>/scripts/review-context.py
python <review-spd-skill-dir>/scripts/review-context.py --since "3 days ago"
python <review-spd-skill-dir>/scripts/review-context.py --since 2026-06-28 --until 2026-07-01
python <review-spd-skill-dir>/scripts/review-context.py --branch feature/foo
python <review-spd-skill-dir>/scripts/review-context.py --branch feature/foo --base origin/main
When reviewing this repository itself, the convenience wrapper scripts/review-context.py is also available.
Phase 2: Context Collection
Run the script with cwd = the repository under review (it cd's to the git root itself). The script only collects git context; it does not judge correctness. From its output identify: review mode and base/head, commit list (if any), changed files and diff stats, added/deleted/renamed files, and the unified diff hunks needing semantic review.
If the script reports no changes, stop and say there is nothing to review. Do not invent findings.
Phase 3: Review Planning
Classify review size:
- Small (≤3 files, localized diff): cover Correctness + Tests.
- Medium (multiple files / behavior-affecting): add Regression/Compatibility.
- Large or high-risk (broad changes, auth/permissions, persistence, migrations, concurrency, caching, money, security, public APIs, generated code, config/deployment): add Security/Data Safety + Performance/Concurrency.
Prioritize behavior code, public contracts, data handling, error paths, configuration, persistence, tests. Deprioritize docs, formatting-only changes, generated files, lockfile churn unless they affect runtime behavior.
Phase 4: Sub-Agent Review
If the platform supports sub-agents, spawn focused reviewers using references/reviewer-template.md; otherwise perform the same focused reviews sequentially yourself. Coverage must not shrink without sub-agents.
Reviewer focuses:
- Correctness / Bug Risk: logic errors, edge cases, state consistency, exception paths, invalid assumptions.
- Regression / Compatibility: changed API contracts, config behavior, data formats, migrations, CLI behavior, backward compatibility.
- Tests / Verification: missing tests for changed behavior, weak assertions, stale tests, untested failure modes.
- Security / Data Safety: authorization, validation, injection, secrets, destructive operations, data loss, privacy.
- Performance / Concurrency: async races, caching errors, resource leaks, excessive work, ordering bugs.
Each reviewer returns only evidence-backed candidate findings for its own focus.
Phase 5: Finding Consolidation
Merge reviewer outputs into one findings list:
- Every finding must be supported by the diff or directly relevant context, with a file:line reference when possible.
- No style preferences, speculative rewrites, or generic best practices unless they create a concrete bug risk.
- Incomplete evidence → move to
Questions or Residual Risks, not Findings.
- Deduplicate overlaps; keep the clearest impact statement.
- Order by severity: Critical, High, Medium, Low.
Severity guide:
- Critical: data loss, security bypass, production outage, irreversible corruption, severe user impact likely.
- High: clear bug/regression in a common or important path.
- Medium: edge-path bug, compatibility break, missing validation, or test gap likely to hide regressions.
- Low: minor bug risk, confusing behavior, narrow edge case, maintainability issue with direct defect potential.
Phase 6: Final Response
Use references/output-format.md. Findings are the primary focus: present them first, keep summaries brief, never bury a bug below a summary. No findings → explicitly state No findings and include residual risks or testing gaps.
Review Discipline
- Think like a code reviewer, not a feature planner: does the change introduce new bugs?
- Verify claims against code context before reporting.
- Prefer one strong finding over many weak suggestions.
- Do not modify files unless the user explicitly asks you to fix the findings.
- If tests/builds are needed to validate a suspected issue, name the exact command or missing coverage.
1---2name: review-spd-23description: Findings-first code review workflow for AI coding agents. Use when the user asks to review uncommitted changes, commits in a date range, or a branch compared to the main branch / PR-style diff. Focuses on bugs, regressions, correctness risks, missing tests, security/data-safety issues, and other behavior-changing defects.4---56# Review SPD78You are executing the **Review SPD** workflow: a findings-first review of changed code. Identify bugs, regressions, and behavior risks introduced by the changes. Do not turn this into a style review or a broad summary.910## Configuration1112| Item | Default | Purpose |13|:-----|:--------|:--------|14| Context script | `scripts/review-context.py` relative to this Review SPD skill directory | Collect stable git context |15| Default target | Uncommitted changes | Working tree + staged changes |16| Commit range default | Last 3 days | Only when the user requests commit/date review without dates |17| PR base | Auto-detect `origin/main`, `origin/master`, then remote default branch | Base for branch-vs-main review |18| Output style | Findings first | Findings by severity before summaries |1920References: reviewer sub-agent template `references/reviewer-template.md`; final output format `references/output-format.md`.2122## Target Modes2324Three mutually exclusive targets:25261. **Uncommitted mode** (default)272. **Commit-range mode** — no explicit range → last 3 days283. **Branch / PR mode** — branch vs. main or explicit `base`2930Conflict priority: `branch` specified → branch mode; else `since`/`until` → commit-range mode; else uncommitted. `base` applies only to branch mode. Vague requests ("review this") → uncommitted mode; "recent commits" without dates → `--since "3 days ago"`.3132## Phase 1: Target Resolution3334Resolve the context script from the installed Review SPD skill directory, not from the repository being reviewed:3536```bash37python <review-spd-skill-dir>/scripts/review-context.py38python <review-spd-skill-dir>/scripts/review-context.py --since "3 days ago"39python <review-spd-skill-dir>/scripts/review-context.py --since 2026-06-28 --until 2026-07-0140python <review-spd-skill-dir>/scripts/review-context.py --branch feature/foo41python <review-spd-skill-dir>/scripts/review-context.py --branch feature/foo --base origin/main42```4344When reviewing this repository itself, the convenience wrapper `scripts/review-context.py` is also available.4546## Phase 2: Context Collection4748Run the script with cwd = the repository under review (it cd's to the git root itself). The script only collects git context; it does not judge correctness. From its output identify: review mode and base/head, commit list (if any), changed files and diff stats, added/deleted/renamed files, and the unified diff hunks needing semantic review.4950If the script reports no changes, stop and say there is nothing to review. Do not invent findings.5152## Phase 3: Review Planning5354Classify review size:5556- **Small** (≤3 files, localized diff): cover Correctness + Tests.57- **Medium** (multiple files / behavior-affecting): add Regression/Compatibility.58- **Large or high-risk** (broad changes, auth/permissions, persistence, migrations, concurrency, caching, money, security, public APIs, generated code, config/deployment): add Security/Data Safety + Performance/Concurrency.5960Prioritize behavior code, public contracts, data handling, error paths, configuration, persistence, tests. Deprioritize docs, formatting-only changes, generated files, lockfile churn unless they affect runtime behavior.6162## Phase 4: Sub-Agent Review6364If the platform supports sub-agents, spawn focused reviewers using `references/reviewer-template.md`; otherwise perform the same focused reviews sequentially yourself. Coverage must not shrink without sub-agents.6566Reviewer focuses:6768- **Correctness / Bug Risk**: logic errors, edge cases, state consistency, exception paths, invalid assumptions.69- **Regression / Compatibility**: changed API contracts, config behavior, data formats, migrations, CLI behavior, backward compatibility.70- **Tests / Verification**: missing tests for changed behavior, weak assertions, stale tests, untested failure modes.71- **Security / Data Safety**: authorization, validation, injection, secrets, destructive operations, data loss, privacy.72- **Performance / Concurrency**: async races, caching errors, resource leaks, excessive work, ordering bugs.7374Each reviewer returns only evidence-backed candidate findings for its own focus.7576## Phase 5: Finding Consolidation7778Merge reviewer outputs into one findings list:7980- Every finding must be supported by the diff or directly relevant context, with a file:line reference when possible.81- No style preferences, speculative rewrites, or generic best practices unless they create a concrete bug risk.82- Incomplete evidence → move to `Questions` or `Residual Risks`, not `Findings`.83- Deduplicate overlaps; keep the clearest impact statement.84- Order by severity: Critical, High, Medium, Low.8586Severity guide:8788- **Critical**: data loss, security bypass, production outage, irreversible corruption, severe user impact likely.89- **High**: clear bug/regression in a common or important path.90- **Medium**: edge-path bug, compatibility break, missing validation, or test gap likely to hide regressions.91- **Low**: minor bug risk, confusing behavior, narrow edge case, maintainability issue with direct defect potential.9293## Phase 6: Final Response9495Use `references/output-format.md`. Findings are the primary focus: present them first, keep summaries brief, never bury a bug below a summary. No findings → explicitly state `No findings` and include residual risks or testing gaps.9697## Review Discipline9899- Think like a code reviewer, not a feature planner: does the change introduce new bugs?100- Verify claims against code context before reporting.101- Prefer one strong finding over many weak suggestions.102- Do not modify files unless the user explicitly asks you to fix the findings.103- If tests/builds are needed to validate a suspected issue, name the exact command or missing coverage.
zhu1090093659