review

What this skill does

<!-- Governing: ADR-0017, SPEC-0015 REQ "Conflict-Marker CI Gate" -->
<!-- Governing: ADR-0015 (Markdown-Native Configuration), SPEC-0014 REQ "Config Resolution Pattern" -->

# Review and Merge PRs

You are reviewing PRs produced by `/sdd:work` using reviewer-responder agent pairs. Each pair processes PRs through exactly one review-response round: the reviewer checks the diff against spec acceptance criteria, the responder addresses feedback, and the reviewer re-evaluates. Approved PRs are merged; unresolved PRs are left with comments for human follow-up. See ADR-0010 and SPEC-0009.

<!-- Governing: ADR-0028 (/loop Autonomous Mode), SPEC-0020 REQ "Lockfile Schema and Acquisition", SPEC-0020 REQ "Budget Schema and Persistence", SPEC-0020 REQ "Telemetry Schema", SPEC-0020 REQ "Resume Contract", SPEC-0020 REQ "Resume Contract Reconciliation" -->

> **Loop Mode (V1, opt-in).** When invoked under `/loop` with the `--loop` flag (and optionally `--pr <N>` for single-PR watch mode), this skill enters autonomous-mode and uses the lockfile + budget primitives documented in `references/loop-primitives.md` (acquired on entry, released on exit) and the telemetry + resume contract documented in `references/loop-telemetry.md` (every iteration appends a `history.jsonl` line; `--resume` reconciles `tracked_prs[]` via SHA equality with `head_sha_at_iteration_end`). The full CLI surface, the active stop conditions (#2 / #3 / #5 / #6 / #8 / #9 / #10 / #11 / #12, with #4 inactive in single-PR mode), and the review-side gates (ambiguous-criteria, budget-escalation, post-feedback-merge, force-unlock, repeated-failure — note: ADR-0010's bounded one-round invariant is preserved per iteration) are wired in story #145 (SPEC-0020). Without `--loop`, behavior is unchanged from the rest of this document and no `.sdd/loop/` artifacts are created.

## Process

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

0. **Resolve artifact paths**: Follow the **Artifact Path Resolution** pattern from `references/shared-patterns.md` to determine the spec directory. If `$ARGUMENTS` contains `--module <name>`, resolve paths relative to that module. The resolved spec directory is `{spec-dir}`.

1. **Parse arguments**: Parse `$ARGUMENTS`.

   **Target resolution:**
   - If a SPEC number is provided (e.g., `SPEC-0003`), find all open PRs whose branch names match the spec's issue branch patterns or whose bodies reference the spec number.
   - If PR numbers are provided (e.g., `101 102 105`), fetch exactly those PRs.
   - If `$ARGUMENTS` is empty (ignoring flags), list available specs by globbing `{spec-dir}/*/spec.md`, read the title from each, and use `AskUserQuestion` to ask which spec's PRs to review.

   **Flag parsing:**
   - `--pairs N`: Number of reviewer-responder pairs. Default: 2 (or CLAUDE.md `Review > Max Pairs`).
   - `--no-merge`: Approve PRs but do not merge them. Default: off.
   - `--dry-run`: Preview which PRs would be reviewed without taking any action. Default: off.
   - `--module <name>`: Resolve artifact paths relative to the named module. Default: none.

2. **Detect tracker**: Follow the "Tracker Detection" flow in the plugin's `references/shared-patterns.md`, but only GitHub, GitLab, and Gitea are supported (PR/MR capability required). If the saved tracker is Beads, Jira, or Linear, inform the user that `/sdd:review` requires a tracker with PR support.

3. **Discover target PRs**: Search the tracker for open PRs matching the target.
   - **GitHub**: `gh pr list --search "SPEC-XXXX" --json number,title,headRefName,body,url --limit 50` or `gh pr view {number} --json number,title,headRefName,body,url` for explicit PR numbers.
   - **Gitea**: Use MCP tools (discovered via `ToolSearch`) to list pull requests.
   - **GitLab**: Use MCP tools or `glab mr list --search "SPEC-XXXX"`.

   If no open PRs are found, inform the user and suggest running `/sdd:work` to create PRs from planned issues.

3a. **Conflict-marker CI gate** (Governing: ADR-0017, SPEC-0015 REQ "Conflict-Marker CI Gate"):

   Before any review logic runs, scan ALL files in every target PR diff for unresolved merge conflict markers. This is a zero-tolerance gate — any file type, any conflict marker means instant rejection.

   **For each target PR:**

   1. Fetch the full diff:
      - **GitHub**: `gh pr diff {number}`
      - **Gitea**: Use MCP tools (discovered via `ToolSearch`) to fetch the PR diff.
      - **GitLab**: Use MCP tools or `glab mr diff`.

   2. Scan every line of the diff for conflict markers: `<<<<<<<`, `=======`, `>>>>>>>`.

   3. **If ANY conflict markers are found:**
      - Collect all offending file paths and line numbers.
      - Submit a `REQUEST_CHANGES` review immediately:
        - **GitHub**: `gh api repos/{owner}/{repo}/pulls/{number}/reviews -f event=REQUEST_CHANGES -f body="..."` with the rejection message below.
        - **Gitea**: Use MCP tools (discovered via `ToolSearch`) to submit a review.
        - **GitLab**: Use MCP tools or `glab` CLI.
      - Rejection message:
        ```
        ## Conflict Markers Detected

        This PR contains unresolved merge conflict markers and cannot be reviewed.

        | File | Line(s) |
        |------|---------|
        | {file-path} | {line-numbers} |

        Please resolve all conflicts and push again.
        ```
      - **Skip this PR entirely** — do not proceed to architecture context loading or review for this PR. Report it as "Rejected: conflict markers" in the final summary.

   4. **If no conflict markers are found**, proceed to step 4 for this PR.

3c. **Tier 4 issues sync** (v5.0.0+):

   <!-- Governing: ADR-0026 (Tiered Index Freshness), SPEC-0019 REQ "Tier 4 Always-Sync Issues for Sprint Skills" -->

   Before computing the topological merge order (Step 11a) and before reviewers query for missing ADR/issue references (Step 4a), sync the `{repo}-issues` qmd collection from the tracker. Subject to the 5-min dedup window per `references/tracker-sync.md` § "Cursor Management".

   1. Read `.sdd/issues/_meta.json`. If `last_sync` is within the last 5 minutes, skip the sync silently.
   2. Otherwise, invoke per-tracker fetch+normalize per `references/tracker-sync.md`. Print: "Syncing N issues from {tracker}…".
   3. On sync failure, surface a one-line warning per `tracker-sync.md` § "Failure Modes and Degradation" and proceed with live tracker queries (the pre-v5 path) for this run. Do NOT block; PR review is the user's primary intent.

4. **Load architecture context** (Governing: SPEC-0009 REQ "Architecture Context Loading"):
   - If a spec identifier is provided or can be inferred from PR metadata (e.g., PR body contains "SPEC-XXXX"), read `spec.md`, `design.md`, and any referenced ADRs from the resolved spec directory. Validate spec pairing per `references/shared-patterns.md` § "Spec Pairing Validation".
   - If no governing spec can be inferred (e.g., PRs specified by number with no spec reference), proceed with general code review only and note in the report that spec compliance could not be verified.
   - This context will be sent to all reviewer agents.

4a. **qmd-aware missing-reference retrieval** (v5.0.0+):

   <!-- Governing: ADR-0024 (qmd as hard dependency), SPEC-0019 REQ "qmd-Smart Sprint Skills" -->

   Reviewers MUST search `{repo}-adrs` and `{repo}-issues` to identify ADRs the PR should reference and prior issues the PR touches. The point: a PR that modifies authentication code should reference the auth ADR (ADR-0011 in the SPEC-0019 example). Without a qmd assist, this requires the reviewer to remember the entire ADR/issue corpus. With qmd, the reviewer surfaces missing references as findings.

   For each PR being reviewed:

   1. Construct a hybrid query per `references/qmd-helpers.md` § "Hybrid Retrieval" derived from the PR's diff:
      - `lex`: keywords from the PR title + file path basenames + named symbols touched
      - `vec`: a one-sentence summary of what the PR