claudetools/.claude/agents/CODE_REVIEW_ST_ENHANCEMENT.md

Code Review Agent - Sequential Thinking Enhancement

Enhancement Date: 2026-01-17 Status: COMPLETED

---

Summary

Enhanced the Code Review Agent to use Sequential Thinking MCP for complex review challenges and repeated rejections. This improves review quality, breaks rejection cycles, and provides better educational feedback to the Coding Agent.

---

What Changed

1. New Section: "When to Use Sequential Thinking MCP"

Location: .claude/agents/code-review.md (after "Decision Matrix")

Added:

• Trigger conditions for invoking Sequential Thinking
• Step-by-step workflow for ST-based reviews
• Complete example of ST analysis in action
• Benefits and anti-patterns

2. Trigger Conditions

Sequential Thinking is triggered when ANY of these occur:

Tough Challenges (Complexity Detection)

• 3+ critical security/performance/logic issues
• Multiple interrelated issues affecting each other
• Architectural problems with unclear solutions
• Complex trade-off decisions
• Unclear root causes

Repeated Rejections (Pattern Detection)

• Code rejected 2+ times
• Same types of issues recurring
• Coding Agent stuck in a pattern
• Incremental fixes not addressing root problems

3. Enhanced Escalation Format

New Format: "Enhanced Escalation (After Sequential Thinking)"

Includes:

• Root cause analysis
• Why previous attempts failed
• Comprehensive solution strategy
• Alternative approaches considered
• Pattern recognition & prevention
• Educational context

Old Format: Still used for simple first rejections

4. Quick Decision Tree

Added simple flowchart at end of document:

1. Count rejections → 2+ = ST
2. Assess complexity → 3+ critical = ST
3. Standard review → minor = fix, major = escalate
4. ST used → enhanced format

5. Summary Section

Added prominent section at top of document highlighting the new ST capability.

---

Files Modified

1. .claude/agents/code-review.md

   • Added Sequential Thinking section (150+ lines)
   • Enhanced escalation format (90+ lines)
   • Quick decision tree (20 lines)
   • Updated success criteria (10 lines)
   • Summary section (15 lines)

2. .claude/agents/CODE_REVIEW_ST_TESTING.md (NEW)

   • Test scenarios demonstrating ST usage
   • Expected behaviors for different scenarios
   • Testing checklist
   • Success metrics

3. .claude/agents/CODE_REVIEW_ST_ENHANCEMENT.md (NEW - this file)

   • Summary of changes
   • Usage guide
   • Benefits

---

How It Works

Standard Flow (No ST)

Code Submitted → Review → Simple Issues → Fix Directly → Approve
                                  ↓
                          Major Issues → Standard Escalation

Enhanced Flow (With ST)

Code Submitted → Review → 2+ Rejections OR 3+ Critical Issues
                                  ↓
                          Sequential Thinking Analysis
                                  ↓
                          Root Cause Identification
                                  ↓
                          Trade-off Evaluation
                                  ↓
                          Enhanced Escalation Format
                                  ↓
                          Comprehensive Solution + Education

---

Example Trigger Scenarios

Scenario 1: Repeated Rejection (TRIGGERS ST)

Rejection 1: SQL injection
Rejection 2: Weak password hashing
→ TRIGGER: Pattern indicates authentication not treated as security-critical
→ ST Analysis: Root cause is mental model problem
→ Enhanced Feedback: Complete auth pattern with threat model

Scenario 2: Multiple Critical Issues (TRIGGERS ST)

Code has:
- SQL injection
- N+1 query problem (2 levels deep)
- Missing indexes
- Inefficient Python filtering

→ TRIGGER: 4 critical issues, multiple interrelated
→ ST Analysis: Misunderstanding of database query optimization
→ Enhanced Feedback: JOIN queries, performance analysis, complete rewrite

Scenario 3: Architectural Trade-offs (TRIGGERS ST)

Code needs refactoring but multiple approaches possible:
- Microservices vs Monolith
- REST vs GraphQL
- Sync vs Async

→ TRIGGER: Unclear which approach fits requirements
→ ST Analysis: Evaluate trade-offs systematically
→ Enhanced Feedback: Comparison matrix, recommended approach with rationale

---

Benefits

1. Breaks Rejection Cycles

• Root cause analysis instead of symptom fixing
• Comprehensive feedback addresses all related issues
• Educational context shifts mental models

2. Better Code Quality

• Identifies architectural issues, not just syntax
• Evaluates trade-offs systematically
• Provides industry-standard patterns

3. Improved Learning

• Explains WHY, not just WHAT
• Threat models for security issues
• Performance analysis for optimization issues
• Complete examples with best practices

4. Token Efficiency

• Fewer rejection cycles = less total tokens
• ST tokens invested upfront save many rounds of back-and-forth
• Comprehensive feedback reduces clarification questions

5. Documentation

• ST thought process is preserved
• Future reviews can reference patterns
• Builds institutional knowledge

---

Usage Guide for Code Reviewer

Step 1: Receive Code for Review

Track mentally: "Is this the 2nd+ rejection?"

Step 2: Assess Complexity

Count critical issues. Are there 3+? Are they interrelated?

Step 3: Decision Point

IF: 2+ rejections OR 3+ critical issues OR complex trade-offs THEN: Use Sequential Thinking MCP

ELSE: Standard review process

Step 4: Use Sequential Thinking (If Triggered)

Use mcp__sequential-thinking__sequentialthinking tool

Thought 1-4: Problem Analysis
- What are ALL the issues?
- How do they relate?
- What's root cause vs symptoms?
- Why did Coding Agent make these choices?

Thought 5-8: Solution Strategy
- What are possible approaches?
- What are trade-offs?
- Which approach fits best?
- What are implementation steps?

Thought 9-12: Prevention Analysis
- Why did this happen?
- What guidance prevents recurrence?
- Are specs ambiguous?
- Should guidelines be updated?

Thought 13-15: Comprehensive Feedback
- How to explain clearly?
- What examples to provide?
- What's acceptance criteria?

Step 5: Use Enhanced Escalation Format

Include ST insights in structured format:

• Root cause analysis
• Comprehensive solution strategy
• Educational context
• Pattern recognition

Step 6: Document Insights

ST analysis is preserved for:

• Future similar issues
• Pattern recognition
• Guideline updates
• Learning resources

---

Testing

See: .claude/agents/CODE_REVIEW_ST_TESTING.md for:

• Test scenarios
• Expected behaviors
• Testing checklist
• Success metrics

---

Configuration

No configuration needed. The Code Review Agent now has these guidelines built-in.

Required MCP: Sequential Thinking MCP must be configured in .mcp.json

Verify MCP Available:

# Check MCP servers
cat .mcp.json | grep sequential-thinking

---

Success Metrics

Track these to validate enhancement effectiveness:

1. Rejection Cycle Reduction

   • Before: Average 3-4 rejections for complex issues
   • After: Target 1-2 rejections (ST on 2nd breaks cycle)

2. Review Quality

   • Root causes identified vs symptoms
   • Comprehensive solutions vs incremental fixes
   • Educational feedback vs directive commands

3. Token Efficiency

   • ST tokens invested upfront
   • Fewer total review cycles
   • Overall token reduction expected

4. Code Quality

   • Fewer security vulnerabilities
   • Better architectural decisions
   • More maintainable solutions

---

Future Enhancements

Potential improvements:

1. Track Rejection Patterns

   • Log common rejection reasons
   • Build pattern library
   • Proactive guidance

2. ST Insights Database

   • Store ST analysis results
   • Reference in future reviews
   • Build knowledge base

3. Automated Complexity Detection

   • Static analysis integration
   • Complexity scoring
   • Auto-trigger ST threshold

4. Feedback Loop

   • Track which ST analyses were most helpful
   • Refine trigger conditions
   • Optimize feedback format

---

Related Files

• Agent Config: .claude/agents/code-review.md
• Testing Guide: .claude/agents/CODE_REVIEW_ST_TESTING.md
• MCP Config: .mcp.json
• Coding Guidelines: .claude/CODING_GUIDELINES.md
• Workflow Docs: .claude/CODE_WORKFLOW.md

---

Rollback

If needed, revert to previous version:

git diff HEAD~1 .claude/agents/code-review.md
git checkout HEAD~1 .claude/agents/code-review.md

Note: Keep testing guide and enhancement doc for future reference.

---

Last Updated: 2026-01-17 Status: COMPLETED & READY FOR USE Enhanced By: Claude Code