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

Bounded Shell Output (MANDATORY)

• For large review files: wc -l then ~/.claude/scripts/safe-read.sh <file> 1 120

• Prefer rg -n over full-file dumps

• Keep verification output concise; include summary + failures only

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:

• Write failing test that exposes the issue

• Verify test fails for the right reason

• Fix the code minimally

• Verify test passes

• 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:

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:

Run quality gates

pnpm typecheck && pnpm lint && pnpm test

Show what was fixed

git log --oneline main..HEAD

Output Format

Address Review Summary

Fixed (In-Scope)

Deferred (Out-of-Scope)

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:

• Gets fixed with a test proving it's fixed

• Becomes a tracked GitHub issue

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