tomevault-io Code Review Workflow Skill
Context (Input)
- PR has unresolved code review comments
- Need systematic approach to address feedback
- Ready to implement reviewer suggestions
- Need to maintain quality standards during review implementation
Task (Function)
Systematically retrieve, categorize, and address all PR code review comments while maintaining quality standards.
Success Criteria: make pr-comments shows 0 unresolved AND make ci shows "✅ CI checks successfully passed!"
Workflow Overview
AI Review Loop → PR Comments → Categorize → Apply by Priority → Verify → Run CI → Done
Quick Start
# 0. Run autonomous AI review + fix loop (Codex default, Claude optional)
make ai-review-loop
# 1. Get comments
make pr-comments
# 2. Apply each suggestion/fix (one commit per comment)
git commit -m "Apply review suggestion: [description]
Ref: [comment URL]"
# 3. Verify all addressed
make pr-comments # Should show 0 unresolved
# 4. Run CI
make ci # Must show "✅ CI checks successfully passed!"
Execution Steps
Step 0: Run Autonomous AI Review Loop
Before addressing PR comments manually, run the autonomous review loop:
make ai-review-loop
This executes scripts/ai-review-loop.sh, which:
- Runs an AI review agent against the current diff (base:
mainby default) - If issues are found (
STATUS: FAIL), runs a fix agent to auto-remediate - Verifies fixes with
make ci - Repeats up to
AI_REVIEW_MAX_ITERtimes (default: 3)
Configuration (all overridable via environment):
| Variable | Default | Description |
|---|---|---|
AI_REVIEW_AGENTS |
codex |
Agent(s) to use (codex, claude) |
AI_REVIEW_BASE |
main |
Base branch for diff comparison |
AI_REVIEW_MAX_ITER |
3 |
Max review/fix iterations (0=∞) |
AI_REVIEW_VERIFY_CMD |
make ci |
Verification command after each fix |
AI_REVIEW_LOG_DIR |
var/ai-review |
Directory for review/fix logs |
Examples:
# Use Claude instead of Codex
AI_REVIEW_AGENTS=claude make ai-review-loop
# Limit to 1 iteration, custom base branch
AI_REVIEW_BASE=develop AI_REVIEW_MAX_ITER=1 make ai-review-loop
# Run both agents
AI_REVIEW_AGENTS=codex,claude make ai-review-loop
Prompt templates: scripts/ai-review-prompts/review.md (reviewer) and scripts/ai-review-prompts/fix.md (fixer).
Step 1: Get PR Comments
make pr-comments # Auto-detect from current branch
make pr-comments PR=62 # Specify PR number
make pr-comments FORMAT=json # JSON output
Output: All unresolved comments with file/line, author, timestamp, URL
Step 2: Categorize Comments
| Type | Identifier | Priority | Action |
|---|---|---|---|
| Committable Suggestion | Code block, "```suggestion" | Highest | Apply immediately, commit separately |
| LLM Prompt | "🤖 Prompt for AI Agents" | High | Execute prompt, implement changes |
| Architecture Concern | Class naming, file location | High | Invoke appropriate skill |
| Question | Ends with "?" | Medium | Answer inline or via code change |
| General Feedback | Discussion, recommendation | Low | Consider and improve |
Step 3: Verify Architecture & Organization
For code changes (suggestions, prompts, new files), invoke verification skills:
| Concern Type | Skill to Invoke |
|---|---|
| Class placement/naming | code-organization |
| DDD patterns | implementing-ddd-architecture |
| Layer violations | deptrac-fixer (if deptrac fails) |
Quick verification: Run make phpcsfixer && make psalm && make deptrac && make unit-tests
Step 4: Apply Changes Systematically
For Committable Suggestions
Apply code change exactly as suggested
Commit with reference:
git commit -m "Apply review suggestion: [brief description] Ref: [comment URL]"
For LLM Prompts
- Copy prompt from comment
- Execute as instructed
- Verify output meets requirements
- Commit with reference
For Architecture/Organization Concerns
- Invoke appropriate skill (
code-organizationorimplementing-ddd-architecture) - Implement recommended changes
- Verify:
make phpcsfixer && make psalm && make deptrac && make unit-tests - Commit with reference
For Questions
- Determine if code change or reply needed
- If code: implement + commit
- If reply: respond on GitHub
For General Feedback
- Evaluate suggestion merit
- Implement if beneficial
- Document reasoning if declined
Step 5: Verify All Addressed
make pr-comments # Should show zero unresolved comments
Step 6: Run Quality Checks
MANDATORY: Run comprehensive CI checks after implementing all changes:
make ci # Must output "✅ CI checks successfully passed!"
If CI fails, invoke appropriate skill:
| Failure Type | Skill to Use |
|---|---|
| Architecture violations | deptrac-fixer |
| Complexity issues | complexity-management |
| Test failures | testing-workflow |
| Mutation testing issues | testing-workflow |
| Code style | Run make phpcsfixer |
| Static analysis | Run make psalm |
DO NOT finish the task until make ci shows: ✅ CI checks successfully passed!
Constraints (Parameters)
NEVER:
- Skip the autonomous AI review loop (
make ai-review-loop) without justification - Skip committable suggestions
- Batch unrelated changes in one commit
- Ignore LLM prompts from reviewers
- Commit without running verification
- Leave questions unanswered
- Accept organizational violations (invoke
code-organizationskill) - Accept architecture violations (invoke
implementing-ddd-architectureskill) - Add suppression/ignore annotations to "fix" review comments or CI failures
- Finish task before
make cishows success message
ALWAYS:
- Run
make ai-review-loopbefore manually addressing PR comments - Apply suggestions exactly as provided
- Commit each suggestion separately with URL reference
- Invoke
code-organizationskill for structural issues - Invoke
implementing-ddd-architectureskill for DDD violations - Run
make ciafter implementing all changes - Address ALL CI failures before finishing
- Mark conversations resolved after addressing
Format (Output)
Commit Message Template:
Apply review suggestion: [concise description]
[Optional: explanation if non-obvious]
Ref: https://github.com/owner/repo/pull/XX#discussion_rYYYYYYY
Final Verification:
✅ make pr-comments shows 0 unresolved
✅ make ci shows "CI checks successfully passed!"
Verification Checklist
- Autonomous AI review loop run via
make ai-review-loop(or skipped with justification) - All PR comments retrieved via
make pr-comments - Comments categorized by type (suggestion/prompt/architecture/question/feedback)
- Architecture verified using appropriate skills
-
make deptracpasses (0 violations) - Committable suggestions applied and committed separately
- LLM prompts executed and implemented
- Questions answered (code or reply)
- General feedback evaluated and addressed
-
make cishows "✅ CI checks successfully passed!" -
make pr-commentsshows zero unresolved - All conversations marked resolved on GitHub
Quick Reference: When to Use Related Skills
During code review, you may need to invoke other skills:
| Issue | Skill to Use |
|---|---|
| Class in wrong directory | code-organization |
| Vague naming | code-organization |
| DDD pattern violations | implementing-ddd-architecture |
| Deptrac failures | deptrac-fixer |
| Complexity too high | complexity-management |
| Test failures | testing-workflow |
| Quality standards | quality-standards |
Related Skills
- code-organization: Enforces "Directory X contains ONLY class type X" and naming conventions
- implementing-ddd-architecture: DDD patterns, layer structure, and boundaries
- deptrac-fixer: Fixes architectural boundary violations
- complexity-management: Reduces cyclomatic complexity
- testing-workflow: Test coverage and mutation testing
- quality-standards: Overall quality metrics and thresholds
- ci-workflow: Comprehensive CI checks
Related Documentation
- Examples:
examples/organization-fixes.md- Real-world organization fix examples - Reference:
reference/quality-standards.md- Quality standards integration details
Converted and distributed by TomeVault — claim your Tome and manage your conversions.