spec-review-remediate

What this skill does

# Spec-Driven PR Review & Remediation

End-to-end PR review pipeline that uses OpenSpec living specs as acceptance criteria, discovers issues via parallel specialized agents, scores confidence, then remediates all findings in one bounded cycle with test verification.

This is a **rigid** skill. Follow every step exactly. Do not skip checkpoints, collapse agent dispatches, or shortcut the scoring phase.

## When to Use

- A PR implements features backed by OpenSpec specs (`openspec/specs/*/spec.md`)
- A security-critical component needs review against its contract, not just code quality
- The user wants both review and fixes in one session
- A PR needs spec compliance verification before merge

## Phase 1 — Gather Context

Fetch all inputs in parallel:

1. **PR metadata**: `gh pr view <number> --json title,body,headRefName,baseRefName,state,files,commits`
2. **PR diff**: `gh pr diff <number>`
3. **Head SHA**: `gh pr view <number> --json headRefOid --jq '.headRefOid'`
4. **OpenSpec living specs**: Read all files matching `openspec/specs/*/spec.md`
5. **CLAUDE.md files**: Discover via `find . -name "CLAUDE.md" -type f`

If no OpenSpec specs exist, halt and inform the user. This skill requires specs as review criteria.

## Phase 2 — Parallel Review (5 Agents)

Dispatch 5 Sonnet agents in parallel. Each receives the PR diff, spec contents, and CLAUDE.md paths. Each returns a list of issues with: description, reason flagged, file and line reference.

| Agent | Focus | Instructions |
|-------|-------|-------------|
| **A1: CLAUDE.md compliance** | Check changes against all CLAUDE.md guidance | Read CLAUDE.md files, then the PR diff. Flag violations of documented conventions, git workflow, patterns. |
| **A2: Shallow bug scan** | Obvious bugs in changed code only | Read the PR diff. Focus on large bugs — logic errors, missing error handling, security gaps. Ignore nitpicks and linter-catchable issues. |
| **A3: Git history context** | Bugs visible from historical context | Run `git blame` and `git log` on modified existing files. Check if changes break established patterns or interact unsafely with existing code. |
| **A4: Previous PR comments** | Recurring feedback from prior PRs | Find recent PRs touching the same files via `gh pr list`. Check their comments for feedback that also applies here. |
| **A5: Spec & comment compliance** | Verify implementation matches spec requirements | For each spec requirement (by ID), verify the code implements it. Flag missing fields, wrong behavior, or deviations. Check in-code comments for compliance. |

## Phase 3 — Confidence Scoring

Deduplicate findings across all 5 agents into a unified issue list. Then dispatch parallel Haiku agents — one per issue — to score confidence.

Pass this rubric verbatim to each scoring agent:

```
Score this issue 0-100:
- 0: Not confident at all. False positive that doesn't stand up to light scrutiny, or pre-existing issue.
- 25: Somewhat confident. Might be real but may be false positive. Agent wasn't able to verify. Stylistic issues not explicitly called out in CLAUDE.md.
- 50: Moderately confident. Verified real issue but may be a nitpick or not happen often. Not very important relative to the rest of the PR.
- 75: Highly confident. Double-checked and verified very likely real. Existing approach is insufficient. Very important, directly impacts functionality, or directly mentioned in CLAUDE.md.
- 100: Absolutely certain. Double-checked, definitely real, will happen frequently. Evidence directly confirms this.

For CLAUDE.md-flagged issues, double-check that CLAUDE.md actually calls out the issue specifically.
```

Filter out issues scoring below 80.

## Phase 4 — Post Formal Review

If high-confidence issues remain (score >= 80), post a review comment to the PR:

```bash
gh pr comment <number> --body "$(cat <<'EOF'
### Code review

Found N issues:

1. **<description>** (<spec ref or reason>)

<link: https://github.com/owner/repo/blob/<full-sha>/path/to/file#L<start>-L<end>>

...

Generated with [Claude Code](https://claude.ai/code)
EOF
)"
```

Requirements for the comment:
- Full git SHA in file links (not abbreviated)
- At least 1 line of context before/after in line ranges
- Spec requirement IDs where applicable (e.g., "PGW-004", "MTL-005")
- Brief descriptions, no emojis

If no issues score >= 80, post: "No issues found. Checked for bugs and spec compliance."

## Phase 5 — Deep Analysis (3 Background Agents)

Launch 3 agents in parallel for deeper analysis:

| Agent | Type | Focus |
|-------|------|-------|
| **Spec compliance matrix** | scope-compliance | Requirement-by-requirement YES/NO/PARTIAL for every spec ID |
| **Code simplifier** | code-simplifier | Simplification opportunities in changed files only |
| **Silent failure hunter** | pr-review-toolkit:silent-failure-hunter | Silent failures, inadequate error handling, inappropriate fallbacks |

## Phase 6 — Consolidate & Tier

Merge findings from Phases 2-5. Deduplicate. Classify each finding:

| Tier | Criteria | Action |
|------|----------|--------|
| **Blocker** | Spec violation, security gap, will break in production | Must fix before merge |
| **Should-fix** | Real issue, high value, low effort | Fix in this session |
| **Nice-to-have** | Code quality, minor spec gaps, cleanup | Present to user, fix if approved |

Present the tiered list to the user before proceeding with fixes.

## Phase 7 — Remediate

Implement blocker and should-fix tier findings:

1. **Parallel subagents** for independent files (files with no cross-dependencies)
2. **Direct editing** for the most complex or interconnected file
3. Each subagent receives: the specific findings for its file, the current file content, and instructions to fix only what is listed

After fixes, invoke the **remediation-loop** skill if any findings were CRITICAL severity — this adds a re-review pass bounded to 2 cycles.

## Phase 8 — Verify & Push

1. Run the full test suite. If tests fail, diagnose and fix regressions (common with hardening changes like `extra='forbid'` or stricter validation).
2. Invoke the **fail-closed-verification** skill before claiming completion.
3. Commit fixes with a descriptive message referencing the review.
4. Push and verify the PR is mergeable: `gh pr view <number> --json mergeable`

## Integration with Other Resilient-Flows Skills

This skill orchestrates two sibling skills:

- **`remediation-loop`**: Invoked in Phase 7 for CRITICAL findings. Provides bounded fix-then-re-review cycles (max 2).
- **`fail-closed-verification`**: Invoked in Phase 8 before claiming done. Ensures parallel reviewer + silent-failure scan with explicit PASS evidence.

## Additional Resources

### Reference Files

- **`references/scoring-rubric.md`** — Full confidence scoring rubric with examples of true positives and false positives, for passing to scoring agents