playbooks

home / skills / phrazzld / claude-config / address-review

address-review skill

/skills/address-review

This skill systematically addresses code review findings in Python projects using TDD to fix in-scope issues and create GitHub issues for out-of-scope items.

npx playbooks add skill phrazzld/claude-config --skill address-review

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
3.4 KB
---
name: address-review
description: |
  Systematically address code review findings using TDD. Fixes in-scope issues, creates GitHub issues for out-of-scope items. Keywords: address review, fix review, review findings, TDD fix, code review response.
effort: high
---

# Address Review Findings

Systematically work through code review findings: TDD for in-scope fixes, GitHub issues for out-of-scope items.

## Usage

```
/address-review              # Accept review from previous context
/address-review ./review.md  # From file
/address-review strict       # Only Critical items
/address-review verify       # Re-review after fixes
```

## Workflow

### 1. Parse Findings

Accept review output (from `/review-branch` or similar). Extract:
- File locations (`file.ts:42`)
- Severity (Critical, Important, Suggestion)
- Issue description
- Recommended fix

### 2. Categorize: In-Scope vs Out-of-Scope

Reference `references/scope-rules.md` for guidance.

**In-scope** (fix now with TDD):
- File in diff
- Critical or Important severity
- Localized fix (doesn't require architectural changes)

**Out-of-scope** (create GitHub issue):
- Pre-existing issues surfaced by review
- Suggestions / nice-to-haves
- Architectural changes requiring broader discussion
- Systemic issues touching many files

**When ambiguous:** Confirm with user via AskUserQuestion.

### 3. Fix In-Scope Items (TDD)

For each in-scope item, follow TDD:

1. **Write failing test** that exposes the issue
2. **Verify test fails** for the right reason
3. **Fix the code** minimally
4. **Verify test passes**
5. **Commit** with conventional format: `fix(scope): description`

Reference `references/tdd-fix-pattern.md` for the detailed workflow.

### 4. Create Issues for Out-of-Scope

For each out-of-scope item:

```bash
gh issue create \
  --title "[Type] Brief description" \
  --body "$(cat <<'EOF'
## Origin

Surfaced during code review of PR #[number] / branch `[branch-name]`

## Finding

[Quote the reviewer's finding]

## Recommended Action

[What should be done]

## Priority

[Critical/Important/Suggestion] — [Why deferred]

---
*Created by /address-review from [reviewer] finding*
EOF
)"
```

Reference `templates/deferred-issue.md` for the template.

### 5. Verify

After all fixes:

```bash
# Run quality gates
pnpm typecheck && pnpm lint && pnpm test

# Show what was fixed
git log --oneline main..HEAD
```

## Output Format

```markdown
## Address Review Summary

### Fixed (In-Scope)
| Finding | Commit | Test Added |
|---------|--------|------------|
| `file.ts:42` — [issue] | abc1234 | Yes |

### Deferred (Out-of-Scope)
| Finding | Issue | Reason |
|---------|-------|--------|
| [issue] | #123 | Pre-existing / Architectural |

### Quality Gates
- [ ] `pnpm typecheck` — ✅
- [ ] `pnpm lint` — ✅
- [ ] `pnpm test` — ✅ (X passed, Y new)

### Next Steps
- [ ] Run `/review-branch verify` to confirm all issues addressed
- [ ] Create PR with `/pr`
```

## Modes

**Default:** Address Critical + Important items. Create issues for Suggestions.

**`strict`:** Only address Critical items. Everything else becomes issues.

**`verify`:** Re-run `/review-branch` after fixes to confirm resolution.

## Philosophy

**No finding gets lost.** Every review item either:
1. Gets fixed with a test proving it's fixed
2. Becomes a tracked GitHub issue

This ensures compounding engineering: reviews produce permanent improvements, not just temporary fixes.

Overview

This skill systematically addresses code review findings by applying test-driven fixes for in-scope items and creating tracked GitHub issues for out-of-scope items. It enforces a repeatable workflow: parse findings, categorize by scope and severity, fix with TDD for applicable items, and defer others with clear issue templates. The goal is to ensure no finding is lost and every change is validated by tests and conventional commits.

How this skill works

The skill ingests review output or a review file, extracts file locations, severities, descriptions, and recommended fixes, then classifies each finding as in-scope or out-of-scope using configurable scope rules. For in-scope items it drives a TDD loop: add a failing test, verify failure, implement a minimal fix, run tests, and commit with a conventional message. Out-of-scope items are converted into GitHub issues using a structured template that records origin, recommended action, and priority.

When to use it

  • After an automated or human code review to systematically act on findings
  • When you want to enforce TDD for every code fix surfaced by reviews
  • Before merging a branch to ensure Critical and Important items are handled
  • When you need to defer suggestions or architectural items but still track them
  • During a re-review pass to verify fixes (verify mode)

Best practices

  • Run the skill on the review output produced by your review tooling so locations and contexts are accurate
  • Prefer localized, minimal code changes for in-scope fixes and always add a failing test first
  • Use the strict mode only when you must limit changes to Critical items
  • Create clear, actionable GitHub issues for deferred work with origin and priority noted
  • Run full quality gates (typecheck, lint, tests) and record results in the summary before creating a PR

Example use cases

  • Fixing a logic bug flagged as Important by adding a unit test that reproduces the bug, then committing the fix
  • Converting multiple Suggestion-level findings into tracked GitHub issues for later prioritization
  • Running verify mode after applying fixes to confirm the review no longer reports the same findings
  • Using strict mode on a release branch to only address Critical security issues immediately
  • Producing a review summary that lists each fixed finding, commits, added tests, and created issues

FAQ

How does the skill decide what is in-scope?

It uses configurable scope rules: in-scope items are in the branch diff, are Critical or Important severity, and are localized fixes that don’t require architecture changes. Ambiguous cases prompt a confirmation question.

What happens to suggestions and architectural changes?

Those are treated as out-of-scope and turned into GitHub issues using a template that records origin, recommended action, and priority so they’re tracked and prioritized later.

How are fixes validated?

Every in-scope fix follows TDD: add a failing test, confirm failure, apply the minimal fix, run tests until passing, and commit with a conventional message. Finally, quality gates are run and results recorded.