plan-from-review

name	plan-from-review
description	Create an implementation plan from PR review feedback
allowed-tools	Bash, Read, Grep, Glob, Write

Plan From Review Skill

Generate an implementation plan based on PR code review feedback. Extracts action items, issues, and suggestions from review comments and creates a structured plan to address them.

Arguments

/plan-from-review <pr-number> [--dry-run]

• <pr-number>: Required. The pull request number to extract review feedback from.
• --dry-run: Optional. Output the plan to console without writing to file.

Execution Flow

1. Detect Repository

# Get repo from git remote
REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')

2. Fetch PR Information

# Get PR details including current HEAD commit
gh pr view $PR_NUMBER --json title,body,headRefName,baseRefName,number,headRefOid

# Get the latest review (prefer REQUEST_CHANGES or COMMENT with content)
gh api repos/$REPO/pulls/$PR_NUMBER/reviews --jq '
  [.[] | select(.body != "" and .body != null)] |
  sort_by(.submitted_at) |
  last'

# Get inline review comments
gh api repos/$REPO/pulls/$PR_NUMBER/comments --paginate

3. Analyze Review Feedback

Do NOT mechanically parse formatted sections. Instead, read and understand the full review conversation:

1. Read the review body - Understand the overall assessment
2. Read all inline comments - Understand specific concerns at each location
3. Read any reply threads - Context may clarify or resolve issues
4. Check the review verdict - APPROVE, REQUEST_CHANGES, or COMMENT

Intelligently determine what's actionable:

• What problems were identified? (bugs, missing tests, security issues, style)
• What was suggested but not required?
• What was just informational or already resolved in discussion?
• Are there implicit issues? (e.g., "this looks complex" may imply refactoring needed)

Categorize by your assessment of severity:

• Must fix: Bugs, security issues, missing critical tests, architectural problems
• Should fix: Missing edge case tests, documentation gaps, code clarity issues
• Nit: Style preferences, optional improvements, nice-to-haves

Skip items that are:

• Already addressed in follow-up comments
• Explicitly marked as non-blocking ("nit:", "optional:", "minor:")
• Questions that were answered without requiring changes
• Praise or approval statements

4. Read Project Guidelines

Before generating the plan:

• Review CODING_GUIDELINES.md for implementation standards
• Review TESTING_GUIDELINES.md for test requirements
• Review COMMIT_GUIDELINES.md for commit structure

5. Determine Output Location

Plans are stored with a revision prefix (short commit SHA) to support multiple review cycles:

# Get current HEAD commit (short SHA)
HEAD_SHA=$(gh pr view $PR_NUMBER --json headRefOid --jq '.headRefOid' | cut -c1-7)

# Extract issue number from branch name if present
BRANCH=$(gh pr view $PR_NUMBER --json headRefName --jq '.headRefName')
# feature/42-something -> 42
ISSUE_NUM=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)

# Determine .ai folder
if [ -n "$ISSUE_NUM" ]; then
  AI_FOLDER=$(ls -d .ai/issue-${ISSUE_NUM}-* 2>/dev/null | head -1)
fi
if [ -z "$AI_FOLDER" ]; then
  # Create folder from PR number
  AI_FOLDER=".ai/pr-${PR_NUMBER}"
fi

# Output file includes revision
OUTPUT_FILE="$AI_FOLDER/review-plan-${HEAD_SHA}.md"

File naming: review-plan-<commit-sha>.md

• Example: review-plan-c9625f7.md
• Allows tracking multiple review cycles
• Easy to correlate plan with specific PR revision

6. Generate Implementation Plan

Write to $AI_FOLDER/review-plan-<sha>.md following the create-plan template structure:

# Implementation Plan: Review Feedback for PR #<number>

## Source
- PR: #<number> - <title> (<link>)
- Review: <reviewer> on <date>
- Revision: `<full-commit-sha>`
- Branch: `<branch-name>`

## Overview
<Brief summary of review feedback - what needs to be addressed>

## Prerequisites
- [ ] PR branch checked out: `<branch-name>`
- [ ] Review feedback understood
- [ ] No blocking questions remain

## Implementation Tasks

### Task 1: <Issue title derived from review comment>
**Files**: `<path/to/file.go>`

**Changes**:
- [ ] <Specific change from review feedback>
- [ ] <Additional change if needed>

**Details**:
<Fix prompt content if available, or detailed description of what to change>

**Severity**: Must fix | Should fix | Nit

### Task 2: <Next issue>
**Files**: `<path/to/file1.go>`, `<path/to/file2.go>`

**Changes**:
- [ ] <Specific change>

**Details**:
<Context from review comment>

**Depends on**: Task 1 (if applicable)

**Severity**: Should fix

### Task N: Add/Update Tests
**Files**: `test/cmd/<file>_test.go`

**Changes**:
- [ ] Add `Test<FunctionName>` - <what it tests>
- [ ] Update existing test for <scenario>

**Test Requirements**: Per TESTING_GUIDELINES.md

## Test Plan

### Tests to Add/Modify
| Test Name | Purpose | File |
|-----------|---------|------|
| `TestXxx` | <from review feedback> | `test/...` |

### Verification
- [ ] All new tests pass
- [ ] Existing tests still pass
- [ ] Edge cases covered

## Documentation Updates
- [ ] `docs/<command>.1.md` - <if mentioned in review>
- [ ] `docs/gitflow-config.5.md` - <if config changes needed>
- [ ] Code comments - <if clarity issues raised>

## Checkpoints

After each checkpoint, verify:
1. `go build ./...` succeeds
2. `go test ./...` passes
3. Review issue addressed

| Checkpoint | After Task | Verification |
|------------|------------|--------------|
| 1 | Task 1 | <must-fix issue resolved> |
| 2 | Task 2 | <should-fix item addressed> |
| 3 | Task N | All tests pass |

## Commit Strategy

Plan commits following COMMIT_GUIDELINES.md:
1. Fix must-fix issues first (group related fixes)
2. Address should-fix items (separate commits for distinct concerns)
3. Implement nits (optional, can be separate PR)

Example commit messages:
- `fix(<scope>): <must-fix issue summary>`
- `test(<scope>): <add missing test>`
- `refactor(<scope>): <address should-fix item>`

## Estimated Scope
- Files to modify: <count>
- New files: <count>
- Tests to add/modify: <count>
- Must fix: <count>
- Should fix: <count>
- Nit: <count>

7. Handle Empty Reviews

If no actionable feedback found:

# Implementation Plan: Review Feedback for PR #<number>

## Source
- PR: #<number> - <title>
- Revision: `<commit-sha>`

## Overview
No action items found in review.

## Status
The review may have been:
- An approval with no requested changes
- Comments without specific action items

**Next steps**:
- Check PR comments directly for context
- Request clarification from reviewer if needed
- Proceed with merge if approved

---

Dry Run Mode

When --dry-run is passed:

• Fetch and parse review data normally
• Output the generated plan to console
• Do NOT write any files

DRY RUN - Plan from PR #123 Review

Would write to: .ai/issue-42-feature-name/review-plan-c9625f7.md

```markdown
# Implementation Plan: Review Feedback for PR #123
...
```

---

Example Output

For a PR with review feedback at revision c9625f7:

# Implementation Plan: Review Feedback for PR #60

## Source
- PR: #60 - Add --no-verify option to finish command
- Review: claude-bot on 2024-02-05
- Revision: `c9625f7a481f09e246e13f5f4307dd3487d0327d`
- Branch: `feature/59-add-no-verify-option-to-finish-command`

## Overview
Implementation is solid with good test coverage. One missing test case identified for squash merge strategy.

## Prerequisites
- [ ] PR branch checked out: `feature/59-add-no-verify-option-to-finish-command`
- [ ] Review feedback understood
- [ ] No blocking questions remain

## Implementation Tasks

### Task 1: Add squash merge test with --no-verify
**Files**: `test/cmd/finish_noverify_test.go`

**Changes**:
- [ ] Add `TestFinishFeatureSquashWithNoVerify` test function
- [ ] Follow TESTING_GUIDELINES.md comment format

**Details**:
Add a test that:
1. Sets up a feature branch with commits
2. Configures squash merge strategy via git config
3. Installs rejecting pre-commit hook
4. Finishes with --no-verify flag
5. Verifies the squash commit succeeds (hook bypassed)

**Severity**: Should fix

## Test Plan

### Tests to Add/Modify
| Test Name | Purpose | File |
|-----------|---------|------|
| `TestFinishFeatureSquashWithNoVerify` | Verify --no-verify works with squash strategy | `test/cmd/finish_noverify_test.go` |

### Verification
- [ ] New test passes
- [ ] Existing 7 tests still pass
- [ ] Covers the `Commit` call after squash merge

## Documentation Updates
- [ ] None required (feature already documented)

## Checkpoints

| Checkpoint | After Task | Verification |
|------------|------------|--------------|
| 1 | Task 1 | Test passes, `go test ./...` succeeds |

## Commit Strategy

test(finish): Add squash merge test for --no-verify flag

Adds TestFinishFeatureSquashWithNoVerify to verify that the --no-verify flag correctly bypasses hooks during squash merge commit operations.

## Estimated Scope
- Files to modify: 1
- New files: 0
- Tests to add: 1
- Must fix: 0
- Should fix: 1
- Nit: 0

---

Multiple Review Cycles

When a PR goes through multiple review cycles:

.ai/issue-59-add-no-verify/
├── analysis.md
├── plan.md                    # Original implementation plan
├── review-plan-c9625f7.md     # First review (revision c9625f7)
├── review-plan-a1b2c3d.md     # Second review after fixes
└── pr_summary.md

Each review plan captures the state at that revision, allowing:

• Historical tracking of review feedback
• Understanding what was fixed between revisions
• Reference for similar future issues

---

Integration with Other Skills

After creating the plan:

• Use /implement .ai/<folder>/review-plan-<sha>.md to execute the fixes
• Use /code-review after implementing to verify changes
• Use /commit to create properly formatted commits