# Review

> Drive an already-open PR's feedback and failing checks to all-green, resolve every thread, run the pre-merge doc gate, then stop for manual merge. Use only when the user asks to address PR feedback or checks; never merges or substitutes for Shepherd monitoring.

- Skill: `harshanandak/review` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add harshanandak/review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/harshanandak/review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: harshanandak (https://skillmd.com/u/harshanandak)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/harshanandak/review

---


Process ALL pull request issues including GitHub Actions failures, review-agent inline comments (Greptile, CodeRabbit, Qodo, or human reviewers), SonarCloud analysis, and other CI/CD checks.

# Review

> **Chain (HARD-GATE):** the successor depends on the change classification (source of truth: lib/workflow/stages.js) — Critical → `verify` (post-merge health check); Standard ENDS at `review`. `verify` is the default/critical-path next. While the PR is still open you may hand off to `shepherd` to watch checks toward merge. `review` never merges.

This skill handles ALL issues that arise after creating a pull request.

## Usage

```bash
/review <pr-number>
```

## What This Skill Does

Before reviewing a diff, read `CODING_STANDARDS.md` from the repository root and apply every relevant rule.

### Step 1: Fetch Complete PR Status
```bash
# Get full PR details including all checks
gh pr view <pr-number> --json number,url,isDraft,reviews,statusCheckRollup,comments

# Check individual status checks
gh pr checks <pr-number>
```

Review ALL status checks:
- GitHub Actions workflows
- Greptile code review (inline comments + summary)
- SonarCloud quality gate
- Any other CI/CD integrations
- Vercel deployments
- Security scanners

### Step 2: Address GitHub Actions Failures

If any GitHub Actions workflows fail:

```bash
# View failed workflow logs
gh run view <run-id> --log-failed

# Identify failure cause:
# - Build failures
# - Test failures
# - Lint/type check failures
# - Deployment failures
# - Security scan failures
```

**For each failure**:
1. **Analyze the error**: Read logs to understand root cause
2. **Fix the issue**: Make necessary code changes
3. **Re-run checks**: GitHub Actions will auto-rerun on push
4. **Document fix**: Note what was fixed in commit message

**Common GitHub Actions Issues**:
- Build failures: Missing dependencies, compilation errors
- Test failures: Failing test cases (should not happen if /validate passed)
- Lint failures: Code style violations
- Type failures: TypeScript type errors
- Deployment failures: Env vars, configuration issues

### Step 3: Process Review-Agent Feedback

Review agents (Greptile, CodeRabbit, Qodo, or human reviewers) provide TWO types of feedback:
1. **Inline comments** on specific code lines
2. **Summary** with overall recommendations

**IMPORTANT**: Use the **systematic review-thread resolution process** documented in `.claude/rules/review-process.md`. This process is author-agnostic — it works the same whichever tool or person left the comment — and has been standardized to ensure:
- All threads are replied to directly (not as separate PR comments)
- All threads are marked as resolved after fixing
- No manual tracking overhead for maintainers

#### 3A. Check Inline Review Comments (Use Systematic Process)

**Step 1: List all unresolved threads**
```bash
bash .claude/scripts/review-resolve.sh list <pr-number> --unresolved
```

This shows:
- Thread ID (for resolving)
- Comment ID (for replying)
- File path and line number
- Issue description

**Step 2: For EACH unresolved thread:**

1. **Understand the issue**
   - Read the comment carefully
   - Check the file and line number

2. **Categorize the comment**:
   - **Valid**: Should be implemented (security issue, bug, clear improvement)
   - **Invalid**: the review agent misunderstood context
   - **Conflicting**: Contradicts research decisions with good reason
   - **Out of scope**: Valid but not for this PR

3. **Fix the issue** (if valid)
   - Make code changes
   - Commit with clear message

4. **Reply and resolve** (for ALL comments, even invalid ones)
   ```bash
   # For valid issues (fixed):
   bash .claude/scripts/review-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
     "✅ Fixed: [description]

     Changed: [what was changed]
     Reason: [why this fixes the issue]
     Commit: [commit-sha]"

   # For invalid/conflicting issues:
   bash .claude/scripts/review-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
     "This approach is correct because:
     - Reasoning: [from design doc]
     - Evidence: [link to source]
     - Alternative considered: [what the review agent suggested]
     - Why rejected: [specific reason]

     See: docs/work/YYYY-MM-DD-<slug>/plan.md (Decision #X)"
   ```

**Step 3: Verify all resolved**
```bash
bash .claude/scripts/review-resolve.sh stats <pr-number>
```
Should show: all review threads resolved.

**See complete process**: `.claude/rules/review-process.md`

#### 3B. Check the Review-Agent Summary
```bash
# Review agents usually post a summary comment on the PR
# Review the overall assessment and recommendations
```

The summary typically includes:
- Overall code quality assessment
- Key issues to address
- Security concerns
- Performance considerations
- Best practice violations

### Step 4: Analyze SonarCloud (via sonarcloud skill)

```bash
# Use sonarcloud skill to query PR-specific issues
/sonarcloud
```

**What SonarCloud does**: Static code analysis for quality, security, and maintainability

**How it helps**:
- Identifies code smells and technical debt
- Finds security vulnerabilities (complementing OWASP Top 10)
- Calculates code coverage
- Tracks code duplication
- Assesses maintainability

**Query PR-specific data**:
- Quality gate status (pass/fail)
- New issues introduced in this PR
- Security hotspots
- Code coverage changes
- Technical debt added

**Prioritize issues**:
1. **Blocker/Critical**: Must fix before merge
2. **Major**: Should fix if valid
3. **Minor/Info**: Optional improvements

### Step 5: Check Other CI/CD Tools

Review any other automated checks:
- **Vercel**: Preview deployment successful?
- **Security scanners**: Any vulnerabilities detected?
- **Custom scripts**: Any failures?
- **Dependency checks**: Outdated or vulnerable packages?

### Step 6: Categorize and Prioritize ALL Issues

Create a master list of all issues from:
- GitHub Actions failures
- Review-agent inline comments
- Review-agent summary recommendations
- SonarCloud issues
- Other CI/CD tool failures

Prioritize by:
1. **Critical**: Blocks merge (failing tests, security vulnerabilities, build failures)
2. **High**: Should address (valid bugs, important improvements)
3. **Medium**: Optional but valuable (code quality, best practices)
4. **Low**: Nice to have (minor refactorings, style suggestions)

### Step 7: Address Issues Systematically

For **GitHub Actions failures** (Critical):
```bash
# Fix the issue
# Commit with clear description
git add .
git commit -m "fix: resolve GitHub Actions failure in <workflow-name>

- Fixed: [specific issue]
- Root cause: [explanation]
- Solution: [what was changed]"

git push
# Actions will auto-rerun
```

For **inline review comments** (Use Systematic Script):
```bash
# Use the standardized review-thread resolution script
# See .claude/rules/review-process.md for complete process

# For valid comments (fixed):
bash .claude/scripts/review-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
  "✅ Fixed: [description]

  Changed: [what was changed]
  Reason: [why this fixes the issue]
  Commit: [commit-sha]"

# For invalid/conflicting comments:
bash .claude/scripts/review-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
  "This approach is correct because:
  - Reasoning: [from design doc]
  - Evidence: [link to source]
  - Alternative considered: [what the review agent suggested]
  - Why rejected: [specific reason]

  See: docs/work/YYYY-MM-DD-<slug>/plan.md (Decision #X)"

# Verify all threads resolved:
bash .claude/scripts/review-resolve.sh stats <pr-number>
```

For **review-agent summary recommendations**:
```bash
# Add a PR comment addressing the summary
gh pr comment <pr-number> --body "## Review Summary Response

Addressed all key recommendations:
- [Recommendation 1]: ✓ Fixed in commit <sha>
- [Recommendation 2]: ✓ Explained (see inline response)
- [Recommendation 3]: ⏭️ Out of scope for this PR (created issue forge-xxx)

All critical and high-priority items resolved."
```

For **SonarCloud issues** (via sonarcloud skill):
```bash
# For critical/blocker issues: Fix immediately
# For security vulnerabilities: Fix immediately
# For code smells: Fix if valid, justify if not

# After fixes, SonarCloud will re-analyze on next push
```

For **other CI/CD failures**:
```bash
# Debug the specific tool's logs
# Fix the underlying issue
# Commit and push
# Verify the check passes
```

### Step 8: Commit ALL Fixes

```bash
git add .
git commit -m "fix: address ALL PR review feedback

GitHub Actions:
- Fixed: [list of workflow failures resolved]

Review agents:
- Fixed: [list of valid inline comments addressed]
- Explained: [list of invalid comments with reasoning]
- Summary: [key recommendations addressed]

SonarCloud:
- Fixed: [security vulnerabilities and critical issues]
- Justified: [code smells that are intentional]

Other CI/CD:
- Fixed: [any other tool failures]

All review feedback resolved, all checks passing."

git push
```

### Step 9: Verify ALL Checks Pass

```bash
# Check status immediately, then poll for at most 60 seconds
gh pr checks <pr-number>

# If checks are still pending after 60 seconds: STOP and tell the user to return
# when CI finishes or new review feedback appears.
#
# Ensure all completed status checks are green:
# ✓ GitHub Actions workflows
# ✓ Review agents (no unresolved critical comments)
# ✓ SonarCloud quality gate
# ✓ Other CI/CD checks
```

### Step 10: Update the Forge issue

```bash
forge comment <id> "PR review complete: all issues addressed, all checks passing"
forge sync
```

## Example Output

```
✓ GitHub Actions: 3 workflows
  - Build: ✓ Passing (was failing, fixed missing dependency)
  - Tests: ✓ Passing
  - Deploy Preview: ✓ Passing

✓ Review-Agent Feedback:
  Inline Comments: 8 total
  - Valid: 5 → Fixed & replied inline
  - Invalid: 2 → Explained with research evidence & replied inline
  - Out of scope: 1 → Noted for future work & replied inline
  - All marked resolved ✓

  Summary:
  - Key recommendations: 3/3 addressed
  - Overall assessment: Ready for merge
  - Posted summary response comment ✓

✓ SonarCloud (via sonarcloud skill):
  Quality Gate: ✓ Passing
  Issues: 3 total
  - Security: 1 → Fixed (SQL injection risk)
  - Code smells: 2 → 1 fixed, 1 justified
  - Coverage: Maintained at 85%

✓ Vercel Preview: ✓ Deployed successfully
✓ Security Scan: ✓ No vulnerabilities

✓ All Issues Addressed:
  - Critical: 2/2 fixed (GitHub Actions build, SonarCloud security)
  - High: 5/5 fixed (Greptile valid comments)
  - Medium: 3/3 addressed (1 fixed, 2 explained)
  - Low: 0 (none found)

✓ Fixes committed: 3c4d5e6
✓ All checks passing: ✓
✓ Forge issue updated: Ready for merge

Next: pre-merge gate — finish docs + confirm CI green, then hand off the PR for merge
```

```
<HARD-GATE: /review exit>
Do NOT declare /review complete until:
1. bash .claude/scripts/review-resolve.sh stats <pr-number> shows all review threads resolved
2. ALL human reviewer comments are either resolved or have a reply with explanation
3. gh pr checks <pr-number> shows all checks passing
4. Context check: confirm design + acceptance on the Forge issue (`forge issue show <id>`); if the beads-context helper is present, run `bash scripts/beads-context.sh validate <id>` and address any warnings
5. Stage transition recorded (structured helper when present; kernel-native comment otherwise):
   if [ -f scripts/beads-context.sh ]; then
     bash scripts/beads-context.sh stage-transition <id> review verify \
       --summary "<all feedback addressed summary>" \
       --decisions "<comment resolutions — valid fixes and justified rejections>" \
       --artifacts "<fixed files, commit SHAs>" \
       --next "<pre-merge gate: finish docs + CI green, then hand off for merge>"
   else
     forge comment <id> "Stage: review complete → ready for verify
Summary: <all feedback addressed summary>
Decisions: <comment resolutions — valid fixes and justified rejections>
Artifacts: <fixed files, commit SHAs>
Next: <pre-merge gate: finish docs + CI green, then hand off for merge>"
   fi
</HARD-GATE>
```

## Pre-merge gate (before merge)

Pre-merge is a doc-update **gate/checkpoint**, not a separate stage — run it here, once feedback is addressed and before the PR is handed off for merge, whenever the change touches anything documented:

1. **Finish the docs on the feature branch** (update only what genuinely changed):
   - `CHANGELOG.md` (always) — entry under `## [Unreleased]` using Keep a Changelog categories, with PR number + issue ID.
   - `README.md` (user-facing), `docs/reference/API_REFERENCE.md` (API), architecture docs (structural).
   - `CLAUDE.md` — **USER section only** (between the USER markers); never touch other managed blocks.
   - `AGENTS.md` (agent config, skills, or cross-agent workflow changes).
   Commit the doc updates to the feature branch and push.
2. **Confirm CI is green** — doc commits re-trigger CI; poll briefly (~60s), then hand off if still pending.
3. **Sync the issue store** — `forge sync`.
4. **Hand off for MANUAL merge** — present the PR and stop. **Never run `gh pr merge`; never auto-merge.** The user merges in the GitHub UI, then runs `/verify`.

## Integration with Workflow

```
Utility: /status  -> Understand current context before starting

Default template:
  /plan      -> Optional default planner; external planners may satisfy /dev entry
  /dev       -> Implement each task with subagent-driven TDD
  /validate  -> Type check, lint, tests, security
  /ship      -> Push + create PR
  /review    -> Address PR feedback
  /verify    -> Post-merge health check

Pre-merge gate: doc updates + CI-green checkpoint embedded in /ship and /review (not a separate stage).
```

## Understanding the Tools

### Greptile
- **What it is**: AI-powered code review bot
- **How it helps**:
  - Context-aware code analysis
  - Catches bugs and security issues
  - Suggests improvements and best practices
  - Provides inline comments and summary
- **How to use feedback**:
  - Inline comments: Address specific code issues
  - Summary: Get overall assessment and key recommendations
  - Reply directly to each comment (not separate)
  - Mark resolved after addressing

### SonarCloud (via sonarcloud skill)
- **What it is**: Static code analysis platform
- **How it helps**:
  - Quality gate enforcement
  - Security vulnerability detection
  - Code smell identification
  - Technical debt tracking
  - Test coverage analysis
- **How to use the skill**:
  - Query PR-specific issues
  - Get quality metrics
  - Identify security hotspots
  - Track code coverage changes
- **Prioritization**:
  - Blocker/Critical: Must fix
  - Major: Should fix if valid
  - Minor/Info: Optional

### GitHub Actions
- **What it is**: CI/CD automation platform
- **How it helps**:
  - Automated testing
  - Build verification
  - Deployment automation
  - Security scanning
  - Quality checks
- **Common failures**:
  - Build: Dependencies, compilation
  - Tests: Failing test cases
  - Lint: Code style violations
  - Deploy: Configuration issues

## Tips

- **Address ALL issues**: Not just one review agent and SonarCloud
- **Prioritize critical**: Fix blockers first (GitHub Actions failures, security issues)
- **Reply inline to review agents**: Respond to each comment directly
- **Post summary response**: Address the review agent's overall assessment
- **Use sonarcloud skill**: Don't just check the web UI
- **Verify all checks**: Ensure everything is green before the pre-merge gate / merge
- **Update the Forge issue**: Keep issue status current
- **Research if needed**: Use WebSearch for unclear suggestions
- **Document fixes**: Clear commit messages for all fixes
- **Don't leave unresolved**: Address every comment and check