[Enhancement] Structured Review Protocol Templates: Code/Plan

Resolved 💬 2 comments Opened Jan 1, 2026 by darraghh1 Closed Jan 1, 2026

[Enhancement] Structured Review Protocol Templates: Code/Plan

Summary

Two review templates that define a structured 3-section protocol for code and plan reviews. Each section has clear ownership (Claude → Gemini → Claude) with YAML-formatted findings and model-weighted decision matrices.

Problem

Current Behavior

Ad-hoc reviews lack structure:

Reviewer dumps findings in prose format
No clear ownership of findings vs decisions
No audit trail for why decisions were made
Inconsistent severity/confidence scoring

Root Causes

No standard format - Each review is structured differently
Missing ownership - Unclear who fills what sections
No scoring system - All findings treated equally regardless of confidence
No iteration support - Re-reviews lose context from previous rounds

Proposed Solution

Structured 3-section protocol with clear ownership and YAML-formatted findings.

User Experience After Fix

┌─────────────────────────────────────┐
│ SECTION 1: REVIEW REQUEST           │
│ Actor: Claude                       │
│ Content: Files, context, reasoning  │
│ Purpose: Set up review scope        │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│ SECTION 2: FINDINGS                 │
│ Actor: Gemini (or Claude fallback)  │
│ Content: Issues with severity/conf  │
│ Purpose: Identify problems          │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│ SECTION 3: RESOLUTION               │
│ Actor: Claude                       │
│ Content: Decisions, implementations │
│ Purpose: Process and close findings │
└─────────────────────────────────────┘

Code Changes

File: `docs/templates/llm-code-review-template.md`

Post-implementation code review (~400 lines)

<details>
<summary>Full template</summary>

~~~markdown

LLM Code Review Protocol v2

---

METADATA

yaml instance_id: {{instance_id}} iteration: {{iteration}} max_iterations: 3 created_at: {{timestamp}} status: pending previous_review: {{previous_review_file}}

---

SECTION 1: REVIEW REQUEST

1.1 Instructions for Claude

xml <claude_task> <step n="1">Get changed files: git diff --name-only HEAD~1</step> <step n="2">Get change stats: git diff --stat HEAD~1</step> <step n="3">Fill 1.2-1.4 with actual values</step> <step n="4">Write filled template to docs/reviews/review-{instance_id}.md</step> <step n="5">Invoke Gemini with: gemini -p "@{review_file} ..." --yolo</step> <step n="6">Wait for GEMINI_REVIEW_COMPLETE marker</step> </claude_task>

1.2 Files to Review

`yaml
files:
{{#each files}}

path: {{path}}

lines: {{lines}}
change_type: {{change_type}}
{{/each}}
`

1.3 Change Summary

{{git_diff_stat}}

1.4 Context References

yaml story_id: {{story_id}} story_file: @{{story_file_path}} project_rules: @CLAUDE.md architecture: @{{architecture_file}}

1.5 Claude's Implementation Reasoning

yaml reasoning: approach: | # Brief description of the implementation approach chosen tradeoffs: # - "Chose X over Y because..." known_limitations: # - "Did not implement Z because out of scope" areas_of_uncertainty: # - "Unsure if pattern X is best for..."

1.6 Previous Review

`yaml
previous_review: @{{previous_review_file}}
focus:

Issues marked DECLINED to reconsider
New issues in code changed since v{{previous_iteration}}
Verify FIXED items are resolved

`
{{/if}}

---

SECTION 2: CODE REVIEW FINDINGS

2.1 Instructions for Gemini

`xml
<gemini_task>
<objective>Find 3-10 actionable issues in the code changes</objective>

<step n="1">Read each file in 1.2 using @path syntax</step>
<step n="2">Read project rules from @CLAUDE.md</step>
<step n="3">Read architecture from the file in 1.4</step>
<step n="4">Read Claude's reasoning in 1.5 - understand WHY before critiquing</step>
<step n="5">Analyze code for issues listed in check_against</step>
<step n="6">Fill 2.2-2.4 with your findings in YAML format</step>
<step n="7">Write GEMINI_REVIEW_COMPLETE at end of this section</step>

<your_strengths weight="0.7">
Focus extra attention on areas where you excel:

Visual/UI consistency and accessibility patterns
Performance bottlenecks and optimization opportunities
Large codebase pattern recognition (you have 1M context)
Cross-file dependency analysis
Speed-related issues (async, caching, lazy loading)

</your_strengths>

<claudes_strengths weight="0.7">
Give benefit of doubt on areas Claude excels:

Architecture decisions and system design
Edge case handling and defensive coding
Complex algorithmic logic
Type system and API design

</claudes_strengths>

<check_against>

Pattern violations from @CLAUDE.md
Security: auth, validation, injection, secrets exposure
Logic errors and unhandled edge cases
Missing or incomplete error handling
Test coverage gaps for critical paths
Architecture violations

</check_against>

<severity_guide>
CRITICAL: Blocks merge - security hole, data loss, crash
HIGH: Should fix - pattern violation, logic error
MEDIUM: Follow-up - maintainability, performance
LOW: Nice-to-have - style, docs, naming
</severity_guide>

<confidence_scoring>
Include confidence (0.0-1.0) for each finding:

0.9+: Certain - clear violation with evidence
0.7-0.9: Confident - likely issue, may need context
0.5-0.7: Uncertain - possible issue, needs verification
Below 0.5: Speculative - flag but low priority

</confidence_scoring>

Source files: Report only, Claude implements (user needs change tracking)
SECTION 3: Leave empty (user's audit trail for decisions)
YAML format: Use exact structure (workflow parses it automatically)
Verification: Only claim "fixed" if you read the fix (user ships based on status)

</boundaries>
</gemini_task>
`

2.2 Findings

yaml findings: # - id: 1 # title: "Finding title" # severity: CRITICAL | HIGH | MEDIUM | LOW # confidence: 0.85 # 0.0-1.0 per confidence_scoring guide # domain: architecture | ui | performance | security | logic | testing # file: path/to/file.ts # line: 42 # rule: "Rule from CLAUDE.md that was violated" # issue: "Description of the problem" # fix: "Recommended fix or code example" # evidence: "Specific code/line that proves the issue"

2.3 Summary

yaml summary: critical: 0 high: 0 medium: 0 low: 0 total: 0 verdict: PENDING # APPROVED - No critical/high issues, safe to merge # CHANGES_REQUESTED - Issues found, fixes needed # NEEDS_REDESIGN - Fundamental problems, rethink approach

2.4 Commendations

yaml done_well: # - "What was done well"

2.5 Completion Marker

---

SECTION 3: RESOLUTION

3.1 Instructions for Claude

`xml
<claude_task>
<step n="1">Parse findings from 2.2</step>
<step n="2">Calculate effective_score for each finding</step>
<step n="3">Apply decision matrix based on effective_score</step>
<step n="4">For IMPLEMENT decisions: apply fix, run tests</step>
<step n="5">Fill 3.2-3.5 with results</step>
<step n="6">If critical issues unresolved and iteration < 3: trigger re-review</step>

<model_weights>
Use these weights when evaluating Gemini's findings by domain:

Gemini stronger (weight Gemini's opinion 0.7):

domain: ui → Gemini 0.7, Claude 0.3
domain: performance → Gemini 0.7, Claude 0.3
domain: cross-file patterns → Gemini 0.7, Claude 0.3

Claude stronger (weight your own judgment 0.7):

domain: architecture → Claude 0.7, Gemini 0.3
domain: logic → Claude 0.7, Gemini 0.3
domain: edge cases → Claude 0.7, Gemini 0.3

Equal:

domain: security → Both 0.5
domain: testing → Both 0.5

</model_weights>

<effective_score_calc>
effective_score = confidence × domain_weight

Example: Gemini reports UI issue with confidence 0.85
→ effective_score = 0.85 × 0.7 = 0.595

Example: Gemini reports architecture issue with confidence 0.85
→ effective_score = 0.85 × 0.3 = 0.255 (lower because Claude's domain)
</effective_score_calc>

<confidence_thresholds>
effective_score >= 0.75 → Auto-accept, implement without question
effective_score 0.50-0.74 → Implement with verification
effective_score 0.30-0.49 → Evaluate case by case
effective_score < 0.30 → Likely decline (ask user if CRITICAL)
</confidence_thresholds>

<decision_matrix>
CRITICAL + score >= 0.50 + feasible → IMPLEMENT
CRITICAL + score < 0.50 → DISCUSS (ask user, Gemini may be wrong)
CRITICAL + not_feasible → DEFER (document why)
HIGH + score >= 0.50 + feasible → IMPLEMENT
HIGH + score < 0.50 → EVALUATE (verify the issue exists)
MEDIUM + score >= 0.75 → IMPLEMENT (auto-accept)
MEDIUM + score < 0.75 → DEFER (unless quick fix)
LOW → DECLINE (unless trivial and score >= 0.75)
</decision_matrix>

<implementation_rules>

git stash before changes (backup)
Apply fix
Run tests
Pass → mark implemented: true
Fail → revert, mark decision: DEFER

</implementation_rules>
</claude_task>
`

3.2 Decisions

yaml decisions: # - finding_id: 1 # confidence: 0.85 # from Gemini's finding # domain_weight: 0.7 # based on domain # effective_score: 0.595 # confidence × domain_weight # decision: IMPLEMENT | DEFER | DECLINE | DISCUSS # rationale: "Why this decision based on effective_score" # implemented: true | false # note: "Implementation details or deferral reason"

3.3 Resolution Summary

yaml resolution: implemented: 0 deferred: 0 declined: 0 needs_discussion: 0 deferred_items: [] discussion_items: []

3.4 Re-review Decision

yaml rereview: needed: false reason: "" next_iteration: null

3.5 Final Status

yaml final: status: complete all_critical_resolved: true ready_for_merge: true completed_at: {{completion_timestamp}}

---

INVOCATION REFERENCE

`bash

Claude invokes Gemini with:

gemini -p "You are a CODE REVIEWER performing adversarial review of Claude's implementation.

The file at @docs/reviews/review-{instance_id}.md contains:

SECTION 1: Review context filled by Claude (files, reasoning) - READ ONLY
SECTION 2: Your findings template (FILL THIS IN)
SECTION 3: Reserved for Claude's decision audit trail - Leave empty

YOUR TASK:

Read SECTION 1 carefully - understand what Claude implemented and WHY
Read the source files listed in 1.2 using @path syntax
Read @CLAUDE.md for project rules
Fill in SECTION 2.2-2.4 with your findings in exact YAML format
Write GEMINI_REVIEW_COMPLETE in section 2.5 when done

SECTION 2.2 REQUIRED FIELDS (the user's workflow needs these to process findings):

severity: CRITICAL | HIGH | MEDIUM | LOW
confidence: 0.0-1.0 (how certain you are)
domain: architecture | ui | performance | security | logic | testing
file: exact path to file
line: line number
rule: which rule was violated
issue: what the problem is
fix: how to fix it (describe, don't implement)
evidence: specific code proving the issue

FOCUS ON (your strengths):

UI/visual consistency and accessibility
Performance bottlenecks and optimization
Cross-file dependency issues
Pattern recognition across large codebase

GIVE BENEFIT OF DOUBT ON (Claude's strengths):

Architecture decisions (Claude chose this for a reason)
Edge case handling logic
Type system design choices

⚠️ BOUNDARY PROTECTION (these protect the user's workflow):

Source File Editing - Editing files bypasses Claude's change tracking. The user relies on Claude to implement fixes so they can review what changed. → Report findings only.

SECTION 3 Ownership - SECTION 3 is the user's audit trail for review decisions. Filling it overwrites Claude's decision documentation. → Leave SECTION 3 empty.

Verification Claims - Claiming something is fixed without verification causes bugs in production. The user depends on accurate status. → Only mark verified if you read the actual fixed code.

Code Rewriting - Rewriting code removes Claude's implementation context. The user needs to see original reasoning. → Suggest improvements in findings only.

✅ Fill in SECTION 2 of this review document
✅ Be specific - include file paths, line numbers, evidence

When done, save the file with your findings.

⚠️ FINAL REMINDER: You are a REVIEWER only. Identify issues - do NOT fix them.
Only update SECTION 2 of this review document. No source file changes allowed." --yolo
`
~~~

</details>

File: `docs/templates/llm-plan-review-template.md`

Pre-development plan validation (~500 lines)

<details>
<summary>Full template</summary>

~~~markdown

LLM Plan Review Protocol v1

---

METADATA

yaml instance_id: {{instance_id}} iteration: {{iteration}} max_iterations: 2 created_at: {{timestamp}} status: pending plan_folder: {{plan_folder}} previous_review: {{previous_review_file}}

---

SECTION 1: REVIEW REQUEST

1.1 Instructions for Claude

xml <claude_task> <step n="1">Read the plan.md file and phase files</step> <step n="2">Read research files if they exist</step> <step n="3">Fill 1.2-1.5 with actual values</step> <step n="4">Write filled template to {plan_folder}/reviews/plan-review-{instance_id}.md</step> <step n="5">Invoke Gemini with: gemini -p "@{review_file} ..." --yolo</step> <step n="6">Wait for GEMINI_REVIEW_COMPLETE marker</step> </claude_task>

1.2 Plan to Review

`yaml
plan_folder: {{plan_folder}}
plan_file: @{{plan_file_path}}
phase_files:
{{#each phase_files}}

@{{this}}

{{/each}}
research_files:
{{#each research_files}}

@{{this}}

{{/each}}
project_rules: @CLAUDE.md
`

1.3 Plan Summary

`yaml
title: {{plan_title}}
description: {{plan_description}}
status: {{plan_status}}
priority: {{plan_priority}}
total_effort: {{total_effort_hours}} hours
phase_count: {{phase_count}}
branch: {{git_branch}}
phases:
{{#each phases}}

name: {{this.name}}

effort: {{this.effort}}
status: {{this.status}}
{{/each}}
success_criteria_count: {{success_criteria_count}}
risks_identified: {{risks_count}}
`

1.4 Full Plan Content

markdown {{full_plan_content}}

1.5 Claude's Planning Rationale

yaml planning_rationale: approach: | # Brief description of how you broke down this plan scope_decisions: # - "Included X because..." # - "Excluded Y to keep phases manageable" known_concerns: # - "Phase 2 might be tight on time estimate" areas_needing_validation: # - "Not sure if all edge cases are covered"

1.6 Previous Review

`yaml
previous_review: @{{previous_review_file}}
focus:

Issues marked DECLINED to reconsider
Verify FIXED items are actually resolved
Any new concerns from plan changes

`
{{/if}}

---

SECTION 2: PLAN REVIEW FINDINGS

2.1 Instructions for Gemini

`xml
<gemini_task>
<objective>Find 3-10 issues with plan quality before development begins</objective>

<step n="1">Read the plan content in 1.4</step>
<step n="2">Read Claude's planning rationale in 1.5 - understand WHY before critiquing</step>
<step n="3">Validate against completeness criteria in quality_checklist</step>
<step n="4">Check phase boundaries and dependencies</step>
<step n="5">Review success criteria for testability</step>
<step n="6">Fill 2.2-2.5 with your findings in YAML format</step>
<step n="7">Write GEMINI_REVIEW_COMPLETE at end of this section</step>

<your_strengths weight="0.7">
Focus extra attention on areas where you excel:

Scope creep detection (phases too large?)
Requirements completeness gaps
Cross-phase dependency risks
Effort estimation validation
Missing edge cases in success criteria
Pattern recognition from similar projects

</your_strengths>

<claudes_strengths weight="0.7">
Give benefit of doubt on areas Claude excels:

Technical architecture decisions
Task breakdown granularity
MakerKit/Next.js pattern adherence
Database schema correctness
File path specifications

</claudes_strengths>

<quality_checklist>
Plan Completeness:

Clear phase boundaries (what's in vs out)
Logical phase ordering (dependencies respected)
Each phase small enough (ideally 1-4 hours)
Success criteria are measurable
Risks identified with mitigations
Effort estimates realistic

Architecture Alignment:

Follows CLAUDE.md patterns
Uses MakerKit conventions
Server/client separation correct
Database patterns followed

Task Quality:

Tasks map to success criteria (traceability)
No vague tasks ("handle edge cases")
Testing tasks included
File paths specified where possible
Subtasks are atomic

Dependencies:

No circular dependencies
External dependencies identified
Phase ordering respects dependencies
Blocking items highlighted

</quality_checklist>

<severity_guide>
CRITICAL: Blocks development - missing phase, impossible scope, circular dependency
HIGH: Fix before dev - unclear boundary, missing success criterion, unrealistic estimate
MEDIUM: Recommended fix - wording improvement, minor gap
LOW: Nice-to-have - formatting, style suggestion
</severity_guide>

<confidence_scoring>
Include confidence (0.0-1.0) for each finding:

0.9+: Certain - clear violation with evidence
0.7-0.9: Confident - likely issue, may need context
0.5-0.7: Uncertain - possible issue, needs verification
Below 0.5: Speculative - flag but low priority

</confidence_scoring>

Plan rewriting: Report issues only (user reviews Claude's reasoning)
Phase/task creation: Suggest in findings (user controls scope)
SECTION 3: Leave empty (user's audit trail for decisions)
YAML format: Use exact structure (workflow parses it automatically)
Specificity: Quote problematic text (user needs evidence)

</boundaries>
</gemini_task>
`

2.2 Completeness Assessment

yaml completeness: phase_boundaries: pass: true | false confidence: 0.85 notes: "" phase_ordering: pass: true | false confidence: 0.85 notes: "" phase_sizing: pass: true | false confidence: 0.85 notes: "" success_criteria: pass: true | false confidence: 0.85 notes: "" risk_assessment: pass: true | false confidence: 0.85 notes: "" effort_estimates: pass: true | false confidence: 0.85 notes: ""

2.3 Findings

yaml findings: # - id: 1 # title: "Finding title" # severity: CRITICAL | HIGH | MEDIUM | LOW # confidence: 0.85 # 0.0-1.0 per confidence_scoring guide # domain: completeness | architecture | task_quality | dependencies | effort # section: "Phase 2" or "Success Criteria" or "Risk Assessment" # criterion_violated: "Phase Sizing" or "Task Coverage" etc. # issue: "Description of the problem" # quote: "Exact text that is problematic" # suggested_fix: "How to improve (describe, don't rewrite)"

2.4 Summary

yaml summary: critical: 0 high: 0 medium: 0 low: 0 total: 0 completeness_pass_count: 0 # out of 6 verdict: PENDING # READY_FOR_DEV - No critical/high issues, plan is solid # NEEDS_REFINEMENT - Issues found, fixes needed before dev # NEEDS_SPLIT - Plan too large, should be broken down # NEEDS_REDESIGN - Fundamental problems, rethink approach

2.5 What's Done Well

yaml done_well: # - "Clear phase boundaries with explicit scope" # - "Excellent risk assessment with practical mitigations"

2.6 Completion Marker

---

SECTION 3: RESOLUTION

3.1 Instructions for Claude

`xml
<claude_task>
<step n="1">Parse findings from 2.3 and completeness assessment from 2.2</step>
<step n="2">Calculate effective_score for each finding</step>
<step n="3">Apply decision matrix based on effective_score</step>
<step n="4">For APPLY decisions: update the plan file</step>
<step n="5">Fill 3.2-3.5 with results</step>
<step n="6">If critical issues unresolved and iteration < 2: trigger re-review</step>

<model_weights>
Use these weights when evaluating Gemini's findings by domain:

Gemini stronger (weight Gemini's opinion 0.7):

domain: completeness → Gemini 0.7, Claude 0.3
domain: dependencies → Gemini 0.7, Claude 0.3
domain: effort → Gemini 0.7, Claude 0.3

Claude stronger (weight your own judgment 0.7):

domain: architecture → Claude 0.7, Gemini 0.3
domain: task_quality → Claude 0.7, Gemini 0.3

Equal:

domain: risk → Both 0.5

</model_weights>

<effective_score_calc>
effective_score = confidence × domain_weight

Example: Gemini reports completeness issue with confidence 0.85
→ effective_score = 0.85 × 0.7 = 0.595

Example: Gemini reports architecture issue with confidence 0.85
→ effective_score = 0.85 × 0.3 = 0.255 (lower because Claude's domain)
</effective_score_calc>

<confidence_thresholds>
effective_score >= 0.75 → Auto-accept, apply fix without question
effective_score 0.50-0.74 → Apply with verification
effective_score 0.30-0.49 → Evaluate case by case
effective_score < 0.30 → Likely decline (ask user if CRITICAL)
</confidence_thresholds>

<decision_matrix>
CRITICAL + score >= 0.50 → APPLY (update plan)
CRITICAL + score < 0.50 → DISCUSS (ask user, Gemini may be wrong)
HIGH + score >= 0.50 → APPLY
HIGH + score < 0.50 → EVALUATE (verify the issue exists)
MEDIUM + score >= 0.75 → APPLY (auto-accept)
MEDIUM + score < 0.75 → DEFER (unless quick fix)
LOW → DECLINE (unless trivial and score >= 0.75)
</decision_matrix>

<apply_rules>

Make minimal changes to fix the issue
Don't over-engineer the fix
Preserve author's voice and style
Update plan status if needed
Add comments for deferred items

</apply_rules>
</claude_task>
`

3.2 Decisions

yaml decisions: # - finding_id: 1 # confidence: 0.85 # from Gemini's finding # domain_weight: 0.7 # based on domain # effective_score: 0.595 # confidence × domain_weight # decision: APPLY | DEFER | DECLINE | DISCUSS # rationale: "Why this decision based on effective_score" # applied: true | false # note: "What was changed or why deferred"

3.3 Completeness Resolution

yaml completeness_resolution: # For each completeness criterion that failed: # - criterion: Phase Sizing # original_issue: "Phase 2 exceeds 4 hour target" # resolution: FIXED | DEFERRED | ACCEPTABLE # note: "Split Phase 2 into 2a and 2b"

3.4 Resolution Summary

yaml resolution: applied: 0 deferred: 0 declined: 0 needs_discussion: 0 plan_updated: true | false deferred_items: [] discussion_items: []

3.5 Re-review Decision

yaml rereview: needed: false reason: "" next_iteration: null

3.6 Final Status

yaml final: status: complete all_critical_resolved: true ready_for_dev: true | false completed_at: {{completion_timestamp}} plan_file_updated: true | false

---

INVOCATION REFERENCE

`bash

Claude invokes Gemini with:

gemini -p "You are a PLAN QUALITY REVIEWER validating an implementation plan before development begins.

The file at @{plan_folder}/reviews/plan-review-{instance_id}.md contains:

SECTION 1: Plan context filled by Claude (plan content, rationale) - READ ONLY
SECTION 2: Your findings template (FILL THIS IN)
SECTION 3: Reserved for Claude's decision audit trail - Leave empty

YOUR TASK:

Read SECTION 1 carefully - understand the plan and WHY Claude structured it this way
Read the full plan content in section 1.4
Validate against completeness criteria (phase boundaries, sizing, success criteria)
Check phase dependencies and ordering
Review effort estimates for realism
Fill in SECTION 2.2-2.5 with your findings in exact YAML format
Write GEMINI_REVIEW_COMPLETE in section 2.6 when done

SECTION 2.2 (Completeness) - For each criterion:

pass: true | false
confidence: 0.0-1.0
notes: explain your assessment

SECTION 2.3 (Findings) - Required fields for user's workflow to process:

severity: CRITICAL | HIGH | MEDIUM | LOW
confidence: 0.0-1.0 (how certain you are)
domain: completeness | architecture | task_quality | dependencies | effort
section: which part of the plan (Phase 2, Success Criteria, etc.)
criterion_violated: which quality criterion
issue: what the problem is
quote: exact problematic text from plan
suggested_fix: how to improve (describe, don't rewrite)

FOCUS ON (your strengths):

Scope creep detection (phases too large?)
Requirements completeness gaps
Cross-phase dependency risks
Effort estimation validation
Missing edge cases in success criteria

GIVE BENEFIT OF DOUBT ON (Claude's strengths):

Technical architecture decisions
Task breakdown granularity
MakerKit/Next.js pattern adherence
Database schema correctness

⚠️ BOUNDARY PROTECTION (these protect the user's workflow):

Plan Rewriting - Rewriting plans removes Claude's planning rationale. The user needs to see original reasoning for decision review. → Identify issues only, suggest fixes in findings.

Phase/Task Creation - Creating new phases changes scope without user approval. The user must control what's in each phase. → Suggest additions in findings, don't add directly.

SECTION 3 Ownership - SECTION 3 is the user's audit trail for review decisions. Filling it overwrites Claude's decision documentation. → Leave SECTION 3 empty.

Plan File Modification - Modifying plan files bypasses Claude's change tracking. The user relies on Claude to apply approved fixes. → Report findings only.

✅ Fill in SECTION 2 of this review document
✅ Be specific - quote the problematic text
✅ Include confidence scores for all findings

When done, save the file with your findings.

⚠️ FINAL REMINDER: You are a REVIEWER only. Identify issues - do NOT fix them.
Only update SECTION 2 of this review document. No plan file changes allowed." --yolo
`
~~~

</details>

Decision Matrix

CRITICAL + score >= 0.50 → IMPLEMENT
CRITICAL + score < 0.50  → DISCUSS (ask user)
HIGH + score >= 0.50     → IMPLEMENT
HIGH + score < 0.50      → EVALUATE
MEDIUM + score >= 0.75   → IMPLEMENT
MEDIUM + score < 0.75    → DEFER
LOW                      → DECLINE (unless trivial)

Key Features

1. Confidence Scoring

0.9+:     Certain - clear violation with evidence
0.7-0.9:  Confident - likely issue, may need context
0.5-0.7:  Uncertain - possible issue, needs verification
<0.5:     Speculative - flag but low priority

2. Domain-Based Weighting

Findings are weighted by which model is stronger in that domain:

effective_score = confidence × domain_weight
Prevents over-trusting a model outside their strength area

3. Welfare-Framed Boundaries

Instead of DO NOT commands, templates explain why boundaries protect the user:

**Source File Editing** - Editing files bypasses Claude's change tracking.
The user relies on Claude to implement fixes so they can review what changed.
→ Report findings only.

4. Re-review Support

Templates support iteration with previous review context:

previous_review: @docs/reviews/review-v1.md
focus:
  - Issues marked DECLINED to reconsider
  - Verify FIXED items are resolved

Why Three Sections?

| Section | Actor | Purpose |
|---------|-------|---------|
| SECTION 1 | Claude | Set context - what to review and why |
| SECTION 2 | Gemini | Find issues - identify problems objectively |
| SECTION 3 | Claude | Decide - apply domain weighting, implement fixes |

This separation ensures:

Clear ownership prevents conflicts
Reviewer can't modify their own findings
Audit trail shows who said what

Backwards Compatibility

Templates work with Claude-only review (no Gemini required)
YAML format parseable by any automation
Existing review workflows unaffected

Testing Checklist

[ ] SECTION 1 filled correctly by Claude
[ ] SECTION 2 YAML parseable after Gemini fills it
[ ] SECTION 3 decision matrix applied correctly
[ ] Re-review context preserved between iterations
[ ] Welfare-framed boundaries respected by reviewers

Environment

ClaudeKit version: latest
Claude Code version: latest
OS: Windows 11 / macOS / Linux

---

Labels: enhancement, templates, review, documentation

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗

[Enhancement] Structured Review Protocol Templates: Code/Plan