19 KiB
19 KiB
Review Modes - Different Review Strategies
This file describes the different review modes available and when to use each one.
Mode Overview
Available Modes:
full: Complete 5-phase review pipeline (default)
quick: Fast review for small changes
commit-only: Generate commits without PR
validate-only: Quality checks and fixes only
pr-only: Create PR from existing commits
analysis: Deep code quality analysis
archive-spec: Move completed spec to completed/
Mode Selection:
- Auto-detect based on context
- User specifies with flags
- Optimize for common workflows
Full Review Mode (Default)
Overview
Full Review Mode:
phases: [Validate, Fix, Commit, Review, Ship]
time: 15-30 minutes
coverage: Comprehensive
output: Complete PR with rich context
When to Use:
- Completed feature ready to ship
- Major changes need thorough review
- Want comprehensive quality validation
- Need multi-agent review insights
- Creating important PR
When NOT to Use:
- Small quick fixes (use quick mode)
- Just need commits (use commit-only)
- Already have commits (use pr-only)
- Just checking quality (use validate-only)
Workflow
Phase 1: Comprehensive Validation (🔍)
- Multi-domain quality checks
- Security vulnerability scanning
- Test coverage analysis
- Documentation completeness
- Quality gate enforcement
Phase 2: Intelligent Auto-Fixing (⚡)
- Simple issue direct fixes
- Complex issue agent delegation
- Parallel fix execution
- Validation after fixes
Phase 3: Smart Commit Generation (📝)
- Change analysis and grouping
- Commit classification
- Conventional commit format
- Specification integration
Phase 4: Multi-Agent Review (🤖)
- refactorer: Code quality review
- security: Security review
- qa: Test coverage review
- implementer: Documentation review
- architect: Architecture review (if needed)
- Consolidated review summary
Phase 5: PR Creation & Shipping (🚀)
- PR title and description generation
- Quality metrics inclusion
- Review insights integration
- Automation setup
- Specification archiving
Example Usage
# Command-based
/review
# Conversation-based
"Review my changes and create a PR"
"Ready to ship this feature"
"Comprehensive review of authentication implementation"
Expected Output
Output Components:
1. Quality Validation Report:
- All quality gates status
- Issues found and fixed
- Metrics (coverage, linting, etc.)
2. Generated Commits:
- List of commits created
- Conventional commit format
- Specification references
3. Multi-Agent Review Summary:
- Code quality insights
- Security assessment
- Test coverage analysis
- Documentation completeness
- Overall recommendation
4. PR Details:
- PR number and URL
- Title and description preview
- Automation applied (labels, reviewers)
- Specification archive status
Time: ~15-30 minutes
Quick Review Mode
Overview
Quick Review Mode:
phases: [Basic Validate, Auto-Fix, Simple Commit, Single Review, Basic PR]
time: 3-5 minutes
coverage: Essential checks only
output: Simple PR with basic context
When to Use:
- Small changes (1-3 files)
- Documentation updates
- Minor bug fixes
- Quick hotfixes
- Low-risk changes
When NOT to Use:
- Major features (use full review)
- Security changes (use full review)
- Complex refactoring (use full review)
- Need detailed analysis (use analysis mode)
Workflow
Phase 1: Basic Validation (🔍)
- Linting check only
- Quick test run
- No deep analysis
- Skip: Security scan, coverage analysis
Phase 2: Auto-Fix Only (⚡)
- Formatting fixes
- Linting auto-fixes
- Skip: Agent delegation
- Skip: Complex fixes
Phase 3: Simple Commit (📝)
- One commit for all changes
- Basic conventional format
- Skip: Intelligent grouping
- Skip: Complex classification
Phase 4: Single Agent Review (🤖)
- Use refactorer agent only
- Quick code quality check
- Skip: Security, QA, implementer reviews
- Skip: Consolidated summary
Phase 5: Basic PR (🚀)
- Simple title and description
- Basic quality metrics
- Skip: Detailed review insights
- Skip: Complex automation
Example Usage
# Command-based
/review --quick
# Conversation-based
"Quick review for this small fix"
"Fast review, just need to ship docs"
"Simple review for typo fixes"
Expected Output
Output Components:
1. Basic Validation:
- Tests: ✅ Passed
- Linting: ✅ Clean
2. Single Commit:
- "fix(api): correct typo in error message"
3. Quick Review:
- Code quality: ✅ Good
- No major issues found
4. Simple PR:
- PR #124 created
- Basic description
- Ready for merge
Time: ~3-5 minutes
Commit-Only Mode
Overview
Commit-Only Mode:
phases: [Basic Validate, Auto-Fix, Smart Commit]
time: 5-10 minutes
coverage: Commit generation focused
output: Organized commits, no PR
When to Use:
- Want organized commits but not ready for PR
- Working on long-running branch
- Need to commit progress
- Plan to create PR later
- Want conventional commits without review
When NOT to Use:
- Ready to ship (use full review)
- Need quality validation (use validate-only)
- Already have commits (no need)
Workflow
Phase 1: Basic Validation (🔍)
- Run linting
- Run tests
- Basic quality checks
- Ensure changes compile/run
Phase 2: Simple Auto-Fixing (⚡)
- Format code
- Fix simple linting issues
- Skip: Complex agent fixes
Phase 3: Smart Commit Generation (📝)
- Analyze all changes
- Group related changes
- Classify by type
- Generate conventional commits
- Include specification references
Phases Skipped:
- Multi-agent review
- PR creation
Example Usage
# Command-based
/review --commit-only
# Conversation-based
"Generate commits from my changes"
"Create organized commits but don't make PR yet"
"I want proper commits but I'm not done with the feature"
Expected Output
Output Components:
1. Validation Status:
- Tests: ✅ Passed
- Linting: ✅ Clean (auto-fixed)
2. Generated Commits:
- 3 commits created:
• "feat(auth): implement JWT generation"
• "test(auth): add JWT generation tests"
• "docs(auth): document JWT implementation"
3. Summary:
- Commits created and pushed
- No PR created (as requested)
- Ready to continue work or create PR later
Time: ~5-10 minutes
Validate-Only Mode
Overview
Validate-Only Mode:
phases: [Comprehensive Validate, Auto-Fix]
time: 5-10 minutes
coverage: Quality checks and fixes
output: Validation report with fixes
When to Use:
- Check code quality before committing
- Want to fix issues without committing
- Unsure if ready for review
- Need quality metrics
- Want to ensure quality gates pass
When NOT to Use:
- Ready to commit (use commit-only)
- Ready to ship (use full review)
- Just need PR (use pr-only)
Workflow
Phase 1: Comprehensive Validation (🔍)
- Multi-domain quality checks
- Security vulnerability scanning
- Test coverage analysis
- Documentation completeness
- Build validation
Phase 2: Intelligent Auto-Fixing (⚡)
- Simple issue direct fixes
- Complex issue agent delegation
- Parallel fix execution
- Re-validation after fixes
Phases Skipped:
- Commit generation
- Multi-agent review
- PR creation
Example Usage
# Command-based
/review --validate-only
# Conversation-based
"Check if my code passes quality gates"
"Validate and fix issues but don't commit"
"Make sure my changes are good quality"
Expected Output
Output Components:
1. Initial Validation Report:
Code Quality: ⚠️ 3 issues
- 2 formatting issues
- 1 unused import
Security: ✅ Clean
- No vulnerabilities
Testing: ✅ Passed
- Coverage: 87%
Documentation: ⚠️ 1 issue
- 1 missing docstring
2. Auto-Fix Results:
- Formatted 2 files
- Removed unused import
- Added missing docstring
3. Final Validation:
Code Quality: ✅ Clean
Security: ✅ Clean
Testing: ✅ Passed
Documentation: ✅ Complete
Status: ✅ All quality gates passing
Ready to commit when you're ready
Time: ~5-10 minutes
PR-Only Mode
Overview
PR-Only Mode:
phases: [Multi-Agent Review, PR Creation]
time: 10-15 minutes
coverage: Review and PR only
output: PR with review insights
When to Use:
- Commits already created manually
- Just need PR creation
- Want review insights without re-validation
- Already validated and fixed issues
- Ready to ship existing commits
When NOT to Use:
- No commits yet (use commit-only or full)
- Need quality validation (use validate-only)
- Need fixes (use full review)
Workflow
Phase 1: Verify Commits (✓)
- Check commits exist
- Analyze commit history
- Extract PR context
Phase 2: Multi-Agent Review (🤖)
- refactorer: Code quality review
- security: Security review
- qa: Test coverage review
- implementer: Documentation review
- Consolidated review summary
Phase 3: PR Creation (🚀)
- Extract title from commits
- Generate comprehensive description
- Include review insights
- Setup automation (labels, reviewers)
- Archive specification
Phases Skipped:
- Validation
- Auto-fixing
- Commit generation
Example Usage
# Command-based
/review --pr-only
# Conversation-based
"Create PR from my existing commits"
"I already committed, just need the PR"
"Make a PR with review insights"
Expected Output
Output Components:
1. Commit Analysis:
- Found 3 commits:
• "feat(auth): implement JWT generation"
• "test(auth): add JWT tests"
• "docs(auth): document JWT"
2. Multi-Agent Review:
- Code quality: ✅ Excellent
- Security: ✅ Secure
- Testing: ✅ Well-tested
- Documentation: ✅ Complete
3. PR Created:
- PR #125: "feat: JWT Authentication"
- URL: https://github.com/user/repo/pull/125
- Labels: enhancement, security
- Reviewers: @security-team
- Specification: spec-feature-auth-001 archived
Time: ~10-15 minutes
Deep Analysis Mode
Overview
Deep Analysis Mode:
phases: [Comprehensive Validate, Extended Review]
time: 20-30 minutes
coverage: In-depth analysis and metrics
output: Detailed quality report
When to Use:
- Need comprehensive quality insights
- Want to understand technical debt
- Planning refactoring
- Assessing code health
- Before major release
When NOT to Use:
- Just need quick check (use validate-only)
- Ready to ship (use full review)
- Simple changes (use quick mode)
Workflow
Phase 1: Comprehensive Validation (🔍)
- All standard quality checks
- Plus: Complexity analysis
- Plus: Technical debt assessment
- Plus: Performance profiling
- Plus: Architecture health
Phase 2: Extended Multi-Agent Review (🤖)
- All agents review (refactorer, security, qa, implementer, architect)
- Plus: Detailed metrics collection
- Plus: Historical comparison
- Plus: Trend analysis
- Plus: Actionable recommendations
Phase 3: Analysis Report Generation (📊)
- Code quality trends
- Security posture
- Test coverage evolution
- Documentation completeness
- Architecture health score
- Technical debt quantification
- Refactoring opportunities
- Performance bottlenecks
Phases Skipped:
- Commit generation
- PR creation
Example Usage
# Command-based
/review --analysis
# Conversation-based
"Deep analysis of code quality"
"Comprehensive quality report"
"Assess codebase health"
Expected Output
Output Components:
1. Quality Metrics:
Code Quality:
- Overall score: 8.5/10
- Complexity: 3.2 avg (↓ from 3.8)
- Duplication: 1.2% (↓ from 2.1%)
- Maintainability: 85/100
Security:
- Security score: 9/10
- Vulnerabilities: 0 critical, 1 low
- Auth patterns: Excellent
- Data protection: Strong
Testing:
- Coverage: 87% (↑ from 82%)
- Test quality: 8/10
- Edge cases: Well covered
- Performance: No regressions
Documentation:
- Completeness: 92%
- API docs: 100%
- Code comments: 88%
- Examples: 3 provided
2. Trends:
- Code quality improving ↑
- Test coverage growing ↑
- Complexity decreasing ↓
- Tech debt reducing ↓
3. Recommendations:
Refactoring Opportunities:
- Extract UserValidator class (medium priority)
- Simplify authenticate() method (low priority)
- Consider caching layer (enhancement)
Performance Optimizations:
- Add database query caching
- Optimize token validation path
Security Hardening:
- Add rate limiting to auth endpoints
- Implement request signing
Technical Debt:
- Total: ~3 days of work
- High priority: 1 day
- Medium: 1.5 days
- Low: 0.5 days
Time: ~20-30 minutes
Specification Archiving Mode
Overview
Specification Archiving Mode:
phases: [Verify Completion, Move Spec, Generate Summary]
time: 2-3 minutes
coverage: Specification management
output: Archived spec with completion summary
When to Use:
- Specification work complete
- All tasks and acceptance criteria met
- PR merged (or ready to merge)
- Want to archive completed work
- Clean up active specifications
When NOT to Use:
- Specification not complete
- PR not created yet (use full review)
- Still working on tasks
Workflow
Phase 1: Verify Completion (✓)
- Check all tasks completed
- Verify acceptance criteria met
- Confirm quality gates passed
- Check PR exists (if applicable)
Phase 2: Move Specification (📁)
- From: .quaestor/specs/active/<spec-id>.md
- To: .quaestor/specs/completed/<spec-id>.md
- Update status → "completed"
- Add completion_date
- Link PR URL
Phase 3: Generate Archive Summary (📝)
- What was delivered
- Key decisions made
- Lessons learned
- Performance metrics
- Completion evidence
Example Usage
# Command-based
/review --archive-spec spec-feature-auth-001
# Conversation-based
"Archive completed specification spec-feature-auth-001"
"Move spec-feature-auth-001 to completed"
"Mark authentication spec as complete"
Expected Output
Output Components:
1. Verification:
✅ All tasks completed (8/8)
✅ Acceptance criteria met (5/5)
✅ Quality gates passed
✅ PR exists (#123)
2. Archive Action:
Moved: spec-feature-auth-001.md
From: .quaestor/specs/active/
To: .quaestor/specs/completed/
Status: completed
Completion Date: 2025-10-19
3. Completion Summary:
Delivered:
- JWT authentication with refresh tokens
- Comprehensive test suite (87% coverage)
- API documentation
- Security review passed
Key Decisions:
- JWT over sessions for scalability
- bcrypt cost factor 12 for security
- Refresh token rotation every 7 days
Lessons Learned:
- Token expiry edge cases need careful testing
- Rate limiting should be in initial design
Metrics:
- Timeline: 3 days (estimated: 5 days) ✅
- Quality: All gates passed ✅
- Tests: 58 tests, 87% coverage ✅
- Security: 0 vulnerabilities ✅
Links:
- PR: #123
- Commits: abc123, def456, ghi789
Time: ~2-3 minutes
Mode Comparison Matrix
Feature Comparison:
Full Quick Commit Validate PR Analysis Archive
Validation ✅ ⚡ ⚡ ✅ ❌ ✅ ✅
Auto-Fixing ✅ ⚡ ⚡ ✅ ❌ ❌ ❌
Commit Generation ✅ ⚡ ✅ ❌ ❌ ❌ ❌
Multi-Agent Review ✅ ⚡ ❌ ❌ ✅ ✅✅ ❌
PR Creation ✅ ⚡ ❌ ❌ ✅ ❌ ❌
Deep Analysis ❌ ❌ ❌ ❌ ❌ ✅ ❌
Spec Archiving ✅ ❌ ❌ ❌ ✅ ❌ ✅
Legend:
✅ = Full feature
⚡ = Simplified version
✅✅ = Extended version
❌ = Not included
Time Comparison:
Mode Time Best For
──────────── ────────────── ────────────────────────────
Full 15-30 min Complete feature shipping
Quick 3-5 min Small changes, hotfixes
Commit 5-10 min Progress commits
Validate 5-10 min Quality check before commit
PR 10-15 min PR from existing commits
Analysis 20-30 min Deep quality insights
Archive 2-3 min Spec completion tracking
Mode Selection Guidelines
Decision Tree
Choose Mode Based on Situation:
Do you have uncommitted changes?
No → Do you want a PR?
Yes → Use: pr-only
No → Use: analysis (for insights)
Yes → Are you ready to ship?
Yes → Use: full (comprehensive review + PR)
No → Do you want to commit?
Yes → Use: commit-only (commits without PR)
No → Do you need quality check?
Yes → Use: validate-only (check + fix)
No → Continue working
Is this a small change (<5 files)?
Yes → Use: quick (fast review)
No → Use: full (comprehensive review)
Do you need detailed metrics?
Yes → Use: analysis (deep insights)
No → Use: appropriate mode above
Is specification complete?
Yes → Use: archive-spec (after PR merged)
No → Continue implementation
Situational Recommendations
Situation → Recommended Mode:
"I finished the feature and want to ship"
→ full: Complete review, commits, PR
"Quick typo fix in docs"
→ quick: Fast review and simple PR
"I want to save progress but not done"
→ commit-only: Organized commits, no PR
"Is my code good quality?"
→ validate-only: Check and fix issues
"I already committed, need PR"
→ pr-only: Review and PR creation
"How healthy is this codebase?"
→ analysis: Comprehensive metrics
"Feature done, PR merged"
→ archive-spec: Move spec to completed/
"Working on experimental feature"
→ commit-only: Save progress commits
"About to start refactoring"
→ analysis: Understand current state
"Hotfix for production"
→ quick: Fast review and ship
Combining Modes
Sequential Mode Usage
Common Workflows:
Development → Validation → Commit → Review → Ship:
1. During development: validate-only (check quality)
2. End of day: commit-only (save progress)
3. Feature complete: full (review and PR)
4. After merge: archive-spec (archive spec)
Before Refactoring → During → After:
1. Before: analysis (understand current state)
2. During: validate-only (ensure quality)
3. After: full (review refactoring + PR)
Long Feature → Progress → Ship:
1. Daily: commit-only (save progress)
2. Weekly: validate-only (quality check)
3. Done: full (comprehensive review + PR)
4. Merged: archive-spec (archive spec)
Comprehensive review mode documentation with clear guidelines for when to use each mode