review

name	review
description	Forge REVIEW stage — drives an already-open PR to all-green by resolving EVERY piece of feedback: failing GitHub Actions / CI checks, Greptile and CodeRabbit inline comments and summaries, and the SonarCloud quality gate. It fixes the code, replies to each thread and marks it resolved until checks pass, then runs the pre-merge doc gate and hands the PR off for MANUAL merge — never runs `gh pr merge`. Use whenever a PR has review feedback or red checks: "address the review comments on PR #123", "the bots flagged issues / Greptile score is low", "fix the failing checks and resolve the threads", "CodeRabbit and SonarCloud left comments", "get my PR merge-ready". This MUTATING feedback-resolution stage is distinct from shepherd (only WATCHES an open PR, changes nothing), verify (POST-merge CI health check + closing issues), ship (pushes the branch + opens the PR), validate (PRE-PR local type/lint/test/security), and sonarcloud / sonarcloud-analysis (only QUERY SonarCloud data).
allowed-tools	Bash, Read, Edit, Grep, Glob
next	verify
terminal	false
handoffs	["shepherd"]

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

/review <pr-number>

What This Skill Does

Step 1: Fetch Complete PR Status

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

# 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 .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)

   # 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 .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

# 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)

# 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):

# 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):

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

# 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):

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

# Debug the specific tool's logs
# Fix the underlying issue
# Commit and push
# Verify the check passes

Step 8: Commit ALL Fixes

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

# 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

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