Review Spd

name: review-spd description: >- 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. version: 1.0.1

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

References: reviewer sub-agent template references/reviewer-template.md; final output format references/output-format.md.

Target Modes

Three mutually exclusive targets:

1. Uncommitted mode (default)
2. Commit-range mode — no explicit range → last 3 days
3. 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
python <review-spd-skill-dir>/scripts/review-context.py --path <subdir>   # 仅审查仓库内某子目录（相对 git 根）

Subdirectory scope: append --path <subdir> (relative to the git root) to restrict collection to that subdirectory; without it the whole repository is scanned.

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.

⚠️ 反模式禁令（行为纪律，非审查范围约束）：

1. 禁止叠补丁：不要为消一条评审再叠一条新评审；回到全局契约面重画方案
2. 禁止修一漏一：改一处须联动验证其余所有相关项与调用点
3. 禁止无全局视野：先画契约面（既有语义/调用点/耦合模块/变更波及半径），再下判断
4. 禁止跨焦点重复：同一问题归属到最匹配焦点，不在多焦点重复报告
5. 禁止推测性 finding：每条 finding 必须附可复现证据（diff hunk/具体命令），严禁空泛建议

每个子代理指令中追加：

「你已收到 open-code-review-delegate 的报告 A/A'（JSON 发现列表）。请遵循上述反模式禁令：

1. 先逐一核对其标出的每项发现是否属实（读取实际代码验证，误报标注为假阳性）
2. 随后独立审查本焦点盲区，挖掘报告 A/A' 未覆盖的缺陷
3. 每条 finding 必须附可复现证据，严禁推测性报告
4. 最终只产出你独立确认或新发现的、证据充分的发现」

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.

Dual output: human-readable text + structured JSON

After the findings-first text, also emit a structured JSON block (see references/output-format.md → "## Structured JSON") so the result can be consumed by an Agent or downstream tooling. The two outputs MUST be derived from the same findings list; never let the JSON disagree with the text.

JSON mode uses open-code-review-delegate-compatible values: workspace (review-spd uncommitted mode), range (review-spd commit-range and branch/PR mode — branch comparisons emit range with from = base (e.g. upstream/main) and to = head (the feature branch), matching review-context.py base/head), commit (single commit). Do not emit a separate branch mode; this keeps the JSON consumable by ocr downstream consumers without translation.

Map each reviewer focus to a JSON category:

Severity maps directly: critical / high / medium / low. files[] and their insertions/deletions come from the Phase 2 context script output. Each finding's start_line/end_line are taken from the diff hunk line numbers of the cited code (matching the path/to/file:line already required in the text findings), so the text and JSON stay aligned. Review SPD has no rule engine, so rules[] carries a single rule field noting review is focus-driven (no rule.json); the path_pattern field is intentionally absent — downstream consumers should tolerate its absence. The category set is intentionally limited to bug | security | performance | test | other (maintainability/style/documentation are excluded by the findings-first discipline); downstream consumers should tolerate the narrower set. This JSON shape is intentionally compatible with the open-code-review-delegate report schema so both skills can feed the same downstream consumers.

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.