| name | marsai:requesting-code-review |
| description | Gate 4 of development cycle - dispatches 7 specialized reviewers (code, business-logic,
security, test, nil-safety, consequences, dead-code) in parallel for comprehensive code review feedback.
|
| trigger | - Gate 4 of development cycle
- After completing major feature implementation
- Before merge to main branch
- After fixing complex bug
|
| skip_when | - Task is purely conversational or informational with no code changes
- Changes are limited to documentation or comments with zero logic modifications
- Code has not been modified since the last completed review cycle
|
| NOT_skip_when | - "Code is simple" → Simple code can have security issues. Review required.
- "Just refactoring" → Refactoring may expose vulnerabilities. Review required.
- "Already reviewed similar code" → Each change needs fresh review.
|
| sequence | {"after":["marsai:dev-testing"],"before":["marsai:dev-validation"]} |
| related | {"complementary":["marsai:dev-cycle","marsai:dev-implementation","marsai:dev-testing"]} |
| input_schema | {"required":[],"optional":[{"name":"unit_id","type":"string","description":"Task or subtask identifier (auto-generated if not provided)"},{"name":"base_sha","type":"string","description":"Git SHA before implementation (auto-detected via git merge-base HEAD main)"},{"name":"head_sha","type":"string","description":"Git SHA after implementation (auto-detected via git rev-parse HEAD)"},{"name":"implementation_summary","type":"string","description":"Summary of what was implemented (auto-generated from git log if not provided)"},{"name":"requirements","type":"string","description":"Requirements or acceptance criteria (reviewers will infer from code if not provided)"},{"name":"implementation_files","type":"array","items":"string","description":"List of files changed (auto-detected via git diff if not provided)"},{"name":"gate0_handoff","type":"object","description":"Full handoff from Gate 0 (only when called from marsai:dev-cycle)"},{"name":"skip_reviewers","type":"array","items":"string","enum":["marsai:code-reviewer","marsai:business-logic-reviewer","marsai:security-reviewer","marsai:test-reviewer","marsai:nil-safety-reviewer","marsai:consequences-reviewer","marsai:dead-code-reviewer"],"description":"Reviewers to skip (use sparingly)"},{"name":"skip_preanalysis","type":"boolean","default":false,"description":"Skip pre-analysis pipeline for faster reviews (reviewers work without static analysis context)"},{"name":"preanalysis_timeout","type":"integer","default":300000,"description":"Timeout for pre-analysis pipeline in milliseconds (default: 5 minutes)"},{"name":"skip_slicing","type":"boolean","default":false,"description":"Skip review slicing step (force full-diff review even for large PRs)"}]} |
| output_schema | {"format":"markdown","required_sections":[{"name":"Review Summary","pattern":"^## Review Summary","required":true},{"name":"Issues by Severity","pattern":"^## Issues by Severity","required":true},{"name":"Reviewer Verdicts","pattern":"^## Reviewer Verdicts","required":true},{"name":"CodeRabbit External Review","pattern":"^## CodeRabbit External Review","required":false},{"name":"Handoff to Next Gate","pattern":"^## Handoff to Next Gate","required":true}],"metrics":[{"name":"result","type":"enum","values":["PASS","FAIL","NEEDS_FIXES"]},{"name":"reviewers_passed","type":"string","description":"X/6 format"},{"name":"issues_critical","type":"integer"},{"name":"issues_high","type":"integer"},{"name":"issues_medium","type":"integer"},{"name":"issues_low","type":"integer"},{"name":"iterations","type":"integer"},{"name":"coderabbit_status","type":"enum","values":["PASS","ISSUES_FOUND","SKIPPED","NOT_INSTALLED"]},{"name":"coderabbit_validation_mode","type":"enum","values":["SUBTASK_LEVEL","TASK_LEVEL"],"description":"Granularity of CodeRabbit validation"},{"name":"coderabbit_units_validated","type":"integer","description":"Number of units (subtasks or tasks) validated by CodeRabbit"},{"name":"coderabbit_units_passed","type":"integer","description":"Number of units that passed CodeRabbit validation"},{"name":"coderabbit_issues","type":"integer","description":"Total number of issues found by CodeRabbit across all units (0 if skipped)"}]} |
Code Review (Gate 4)
Overview
Dispatch all seven reviewer subagents in parallel for fast, comprehensive feedback:
- marsai:code-reviewer - Architecture, design patterns, code quality
- marsai:business-logic-reviewer - Domain correctness, business rules, edge cases
- marsai:security-reviewer - Vulnerabilities, authentication, OWASP risks
- marsai:test-reviewer - Test quality, coverage, edge cases, anti-patterns
- marsai:nil-safety-reviewer - Nil/null pointer safety for Go and TypeScript
- marsai:consequences-reviewer - Ripple effects, caller chain impact, downstream consequences
- marsai:dead-code-reviewer - Orphaned code detection, reachability analysis, dead dependency chains
Core principle: All 7 reviewers run simultaneously in a single message with 7 Task tool calls.
CRITICAL: Role Clarification
This skill ORCHESTRATES. Reviewer Agents REVIEW.
| Who | Responsibility |
|---|
| This Skill | Dispatch reviewers, aggregate findings, track iterations |
| Reviewer Agents | Analyze code, report issues with severity |
| Implementation Agent | Fix issues found by reviewers |
Step 1: Gather Context (Auto-Detect if Not Provided)
This skill supports TWO modes:
1. WITH INPUTS: Called by any skill/user that provides structured inputs (unit_id, base_sha, etc.)
2. STANDALONE: Called directly without inputs - auto-detects everything from git
FOR EACH INPUT, check if provided OR auto-detect:
1. unit_id:
IF provided → use it
ELSE → generate: "review-" + timestamp (e.g., "review-20241222-143052")
2. base_sha:
IF provided → use it
ELSE → Execute: git merge-base HEAD main
IF git fails → Execute: git rev-parse HEAD~10 (fallback to last 10 commits)
3. head_sha:
IF provided → use it
ELSE → Execute: git rev-parse HEAD
4. implementation_files:
IF provided → use it
ELSE → Execute: git diff --name-only [base_sha] [head_sha]
5. implementation_summary:
IF provided → use it
ELSE → Execute: git log --oneline [base_sha]..[head_sha]
Format as: "Changes: [list of commit messages]"
6. requirements:
IF provided → use it
ELSE → Set to: "Infer requirements from code changes and commit messages"
(Reviewers will analyze code to understand intent)
AFTER AUTO-DETECTION, display context:
┌─────────────────────────────────────────────────────────────────┐
│ 📋 CODE REVIEW CONTEXT │
├─────────────────────────────────────────────────────────────────┤
│ Unit ID: [unit_id] │
│ Base SHA: [base_sha] │
│ Head SHA: [head_sha] │
│ Files Changed: [count] files │
│ Commits: [count] commits │
│ │
│ Dispatching 7 reviewers in parallel... │
└─────────────────────────────────────────────────────────────────┘
Step 1.5: Pre-Fetch Shared Context (MANDATORY)
⛔ CRITICAL: Gather ALL shared context ONCE before dispatching reviewers. Do NOT let individual reviewers WebFetch or git-diff independently — 7 agents fetching the same data wastes minutes per reviewer.
shared_context = {}
1. Read the full diff ONCE:
shared_context.diff = Execute: git diff [base_sha] [head_sha]
2. Detect project language from implementation_files:
shared_context.language = "typescript" (if *.ts files) | "go" (if *.go files)
3. WebFetch standards ONCE (based on detected language):
if language == "typescript":
shared_context.standards = WebFetch typescript.md standards
if language == "go":
shared_context.standards = WebFetch go.md standards
4. Read standards-coverage-table.md ONCE:
shared_context.coverage_table = Read standards-coverage-table.md
NOTE: This context is injected into EVERY reviewer prompt below via
[shared_context.diff], [shared_context.standards], [shared_context.coverage_table].
Reviewers MUST NOT WebFetch or run git diff themselves.
Step 2: Initialize Review State
review_state = {
unit_id: [from input],
base_sha: [from input],
head_sha: [from input],
reviewers: {
code_reviewer: {verdict: null, issues: []},
business_logic_reviewer: {verdict: null, issues: []},
security_reviewer: {verdict: null, issues: []},
test_reviewer: {verdict: null, issues: []},
nil_safety_reviewer: {verdict: null, issues: []},
consequences_reviewer: {verdict: null, issues: []},
dead_code_reviewer: {verdict: null, issues: []}
},
aggregated_issues: {
critical: [],
high: [],
medium: [],
low: [],
cosmetic: []
},
iterations: 0,
max_iterations: 3,
slicing: {
enabled: false,
slice_count: 0,
slices: [],
cross_cutting_issues: []
}
}
Step 2.5: Pre-Analysis Context (Optional)
If pre-analysis context files exist in docs/codereview/, read them to provide additional context to reviewers.
Step 2.5.1: Read Context Files (if available)
Check for existing context files:
| Reviewer | Context File |
|---|
marsai:code-reviewer | docs/codereview/context-code-reviewer.md |
marsai:security-reviewer | docs/codereview/context-security-reviewer.md |
marsai:business-logic-reviewer | docs/codereview/context-business-logic-reviewer.md |
marsai:test-reviewer | docs/codereview/context-test-reviewer.md |
marsai:nil-safety-reviewer | docs/codereview/context-nil-safety-reviewer.md |
marsai:consequences-reviewer | docs/codereview/context-consequences-reviewer.md |
marsai:dead-code-reviewer | docs/codereview/context-dead-code-reviewer.md |
Store each file's content in preanalysis_state.context[reviewer_name].
If a context file is missing or empty, log warning and continue (reviewer will work without context).
preanalysis_state = {
enabled: true,
success: false,
context: {
"marsai:code-reviewer": null,
"marsai:security-reviewer": null,
"marsai:business-logic-reviewer": null,
"marsai:test-reviewer": null,
"marsai:nil-safety-reviewer": null,
"marsai:consequences-reviewer": null,
"marsai:dead-code-reviewer": null
}
}
Step 2.7: Review Slicing (Adaptive Cohesion-Based Analysis)
See shared-patterns/reviewer-slicing-strategy.md for full rationale, cost analysis, and dedup strategy.
Run the review slicer to evaluate semantic cohesion and determine optimal review strategy. For small/focused PRs, this adds ~5 seconds and changes nothing. For large multi-themed PRs, it dramatically improves review depth by using package structure, import relationships, and function-level change context to produce semantically meaningful slices.
Skip Override: The skip_slicing parameter allows bypassing this step. When skipped, the standard full-diff flow is used regardless of PR size.
IF skip_slicing == true:
→ review_state.slicing.enabled = false
→ Display: "Review slicing skipped by parameter. Using full-diff review."
→ Skip to Step 3
Step 2.7.1: Collect Inputs for Adaptive Slicer
FILE_LIST=$(git diff --name-only $BASE_SHA $HEAD_SHA)
DIFF_STATS=$(git diff --stat $BASE_SHA $HEAD_SHA)
PACKAGE_MAP={}
for file in $FILE_LIST; do
dir=$(dirname "$file")
basename=$(basename "$file")
done
IMPORT_HINTS={}
for file in $FILE_LIST; do
imports=$(grep -E '^\s*(import |from |require\()' "$file" 2>/dev/null || true)
done
CHANGE_SUMMARY=$(git diff $BASE_SHA $HEAD_SHA -U0 --diff-filter=d | \
grep -E '^(diff --git|@@)' | \
sed -n '/^diff --git/{s|diff --git a/\(.*\) b/.*|\1:|;h;d}; /^@@/{s/.*@@\s*//;H;x;s/\n/ /;p}')
Graceful input collection: If PACKAGE_MAP, IMPORT_HINTS, or CHANGE_SUMMARY collection fails (e.g., binary files, unusual repo structure, permission errors), log a warning and continue with whatever inputs succeeded. These enriched inputs improve slicer accuracy but are NOT required — the slicer has its own fallback logic for missing signals.
Step 2.7.2: Dispatch Review Slicer Agent
Task:
subagent_type: "marsai:review-slicer"
description: "Evaluate PR cohesion and decide review slicing"
prompt: |
## Review Slicing Request
```
[FILE_LIST]
```
```
[DIFF_STATS]
```
```json
[PACKAGE_MAP as JSON]
```
```json
[IMPORT_HINTS as JSON]
```
```
[CHANGE_SUMMARY]
```
Evaluate semantic cohesion using all available signals.
Apply three-phase reasoning (volume → cohesion → cost-benefit).
Return structured JSON with your decision and detailed reasoning.
Step 2.7.3: Parse Slicer Response and Update State
Parse JSON response from marsai:review-slicer.
IF slicer_response.shouldSlice == false:
→ review_state.slicing.enabled = false
→ Display:
┌─────────────────────────────────────────────────────────────────┐
│ REVIEW SLICING: NOT NEEDED │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Reason: [slicer_response.reasoning] │
│ Proceeding with full-diff review (standard flow). │
│ │
└─────────────────────────────────────────────────────────────────┘
→ Continue to Step 3 as-is (no change to current flow)
IF slicer_response.shouldSlice == true:
→ review_state.slicing.enabled = true
→ review_state.slicing.slice_count = slicer_response.slices.length
→ review_state.slicing.slices = slicer_response.slices (each with empty results initially)
→ Display:
┌─────────────────────────────────────────────────────────────────┐
│ REVIEW SLICING: ACTIVE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Reason: [slicer_response.reasoning] │
│ Slices: [N] │
│ │
│ ┌──────────────────┬──────────────────────────┬───────┐ │
│ │ Slice │ Description │ Files │ │
│ ├──────────────────┼──────────────────────────┼───────┤ │
│ │ api-handlers │ HTTP handlers, middleware │ 12 │ │
│ │ domain-models │ Entities, business rules │ 8 │ │
│ │ infrastructure │ Helm charts, CI/CD │ 5 │ │
│ └──────────────────┴──────────────────────────┴───────┘ │
│ │
│ Dispatching 7 reviewers x [N] slices = [7*N] review tasks... │
│ │
└─────────────────────────────────────────────────────────────────┘
→ Continue to Step 3 (Sliced Dispatch variant)
Step 2.7.4: Slicer Failure Handling and Graceful Degradation
IF slicer agent fails (timeout, error, malformed JSON):
→ Log warning: "Review slicer failed: [error]. Falling back to full-diff review."
→ review_state.slicing.enabled = false
→ Continue to Step 3 as-is (graceful degradation, not a blocker)
NOTE: Input collection failures are NOT blockers.
- If PACKAGE_MAP collection fails → dispatch slicer without it (slicer uses file paths as fallback)
- If IMPORT_HINTS collection fails → dispatch slicer without it (slicer infers from naming conventions)
- If CHANGE_SUMMARY collection fails → dispatch slicer without it (slicer relies on diff stats)
- The slicer has its own internal fallback logic for missing signals.
- MUST always include FILE_LIST and DIFF_STATS (these are the minimum required inputs).
Step 3: Dispatch All 7 Reviewers in Parallel
⛔ CRITICAL: All 7 reviewers MUST be dispatched in a SINGLE message with 7 Task calls.
Model: All reviewers use model: "sonnet". Seven specialized Sonnet reviewers with different lenses provide comprehensive coverage. The redundancy of 7 parallel agents compensates for individual model differences, while reducing wall-clock time from ~40 min (Opus) to ~8-12 min.
Step 3 Mode Selection
IF review_state.slicing.enabled == false:
→ STANDARD MODE: Dispatch 7 reviewers on full diff (unchanged from current flow)
→ Continue with Step 3 dispatch below as-is
IF review_state.slicing.enabled == true:
→ SLICED MODE: Skip standard dispatch. Go to Step 3-S (Sliced Dispatch) below.
Step 3-S: Sliced Dispatch (When Slicing Is Active)
⛔ CRITICAL: All 7 reviewers run on ALL slices. No "relevant reviewer" routing. More eyes = more safety.
FOR EACH slice IN review_state.slicing.slices:
1. Generate scoped diff for this slice:
git diff [base_sha] [head_sha] -- [slice.files...]
2. Filter pre-analysis context for this slice (if available):
FOR EACH reviewer_context IN preanalysis_state.context:
→ Extract only sections/paragraphs that mention files in slice.files
→ Store as slice_filtered_context[reviewer_name]
(If a context section mentions no files in this slice, exclude it entirely)
3. Dispatch all 7 reviewers with slice-scoped context:
⛔ All 7 MUST be dispatched in a SINGLE message with 7 Task calls (per slice)
The prompt for each reviewer is IDENTICAL to the standard Step 3 prompts below,
with these substitutions:
- model: "sonnet" (same as standard dispatch — all reviewers use Sonnet)
- [implementation_files] → slice.files (not full file list)
- Git diff content → scoped diff from step 1 above
- Pre-Analysis Context → slice_filtered_context[reviewer_name]
- Add to prompt header:
"**Review Scope:** Slice '[slice.name]' — [slice.description]
**Files in this slice:** [slice.files.join(', ')]
**Note:** This is a thematic slice of a larger PR. Focus your review
on these files. Other files in this PR are being reviewed separately."
4. Collect results per slice:
review_state.slicing.slices[i].reviewer_results = {
code_reviewer: {verdict, issues},
business_logic_reviewer: {verdict, issues},
... (all 7)
}
AFTER ALL SLICES COMPLETE:
→ Merge and deduplicate (Step 3-S-Merge below)
→ Continue to Step 4 with merged results
Step 3-S-Merge: Merge and Deduplicate Slice Results
⛔ MANDATORY: Dedup MUST run before presenting results to Step 4.
1. COLLECT all issues from all slices into a single list:
all_issues = []
FOR EACH slice IN review_state.slicing.slices:
FOR EACH reviewer IN slice.reviewer_results:
FOR EACH issue IN reviewer.issues:
all_issues.push({
...issue,
source_slice: slice.name,
source_reviewer: reviewer.name
})
2. EXACT MATCH DEDUP:
Group by (reviewer_name + file + line).
If duplicates exist → keep one instance.
3. FUZZY MATCH DEDUP:
For issues at the same file:line from DIFFERENT reviewers or slices:
IF description_similarity(issue_a, issue_b) > 80%:
→ Keep the issue with the longer/more detailed description
→ Add metadata: "Also flagged by: [other_reviewer] in [other_slice]"
→ This indicates higher confidence (multiple independent detections)
4. CROSS-CUTTING DETECTION:
Issues found across 2+ slices (same file:line, similar description):
→ Tag as "cross-cutting concern"
→ Add to review_state.slicing.cross_cutting_issues
→ Surface prominently in consolidated report — cross-cutting issues
often signal architectural problems
5. MERGE VERDICTS:
Per reviewer, final verdict = worst verdict across all slices.
(If marsai:security-reviewer PASSes on slice A but FAILs on slice B,
the merged verdict is FAIL.)
6. POPULATE review_state:
review_state.reviewers = merged verdicts + merged issues (deduped)
review_state.aggregated_issues = all issues categorized by severity (deduped)
7. ADD SLICING NOTE to output:
"Review was sliced into [N] thematic groups for deeper analysis."
Standard Mode Dispatch (When Slicing Is NOT Active)
The following dispatch is used when review_state.slicing.enabled == false.
⛔ CRITICAL: Inject [shared_context.diff] into each reviewer prompt under "## Git Diff". Reviewers MUST NOT run git diff themselves. The diff was pre-fetched in Step 1.5.
Task:
subagent_type: "marsai:code-reviewer"
model: "sonnet"
description: "Code review for [unit_id]"
prompt: |
## Code Review Request
**Unit ID:** [unit_id]
**Base SHA:** [base_sha]
**Head SHA:** [head_sha]
[implementation_summary]
[requirements]
[implementation_files]
[shared_context.diff]
[IF preanalysis_state.context["marsai:code-reviewer"] exists: INSERT it]
- Architecture and design patterns
- Code quality and maintainability
- Naming conventions
- Error handling patterns
- Performance concerns
- **File size compliance** — Any file > 300 lines (excluding auto-generated: *.d.ts, */generated/*, */mocks/*) MUST be flagged as MEDIUM+ issue. Files > 500 lines = CRITICAL. See shared-patterns/file-size-enforcement.md.
**Standards have been pre-fetched by the orchestrator. Do NOT WebFetch — use the context below.**
[shared_context.standards]
[shared_context.coverage_table]
**Check the changed code against ALL applicable sections.**
**Include a Standards Compliance section in your output** listing which standards were verified and any violations found.
| Severity | Description | File:Line | Recommendation |
|----------|-------------|-----------|----------------|
| [CRITICAL/HIGH/MEDIUM/LOW/COSMETIC] | [issue] | [location] | [fix] |
| Standard | Section | Status | Evidence |
|----------|---------|--------|----------|
| [module.md] | [section name] | ✅/❌ | [file:line or N/A] |
[positive observations]
Task:
subagent_type: "marsai:business-logic-reviewer"
model: "sonnet"
description: "Business logic review for [unit_id]"
prompt: |
## Business Logic Review Request
**Unit ID:** [unit_id]
**Base SHA:** [base_sha]
**Head SHA:** [head_sha]
[implementation_summary]
[requirements]
[shared_context.diff]
[IF preanalysis_state.context["marsai:business-logic-reviewer"] exists: INSERT it]
- Domain correctness
- Business rules implementation
- Edge cases handling
- Requirements coverage
- Data validation
| Severity | Description | File:Line | Recommendation |
|----------|-------------|-----------|----------------|
| [CRITICAL/HIGH/MEDIUM/LOW/COSMETIC] | [issue] | [location] | [fix] |
| Requirement | Status | Evidence |
|-------------|--------|----------|
| [req] | ✅/❌ | [file:line] |
Task:
subagent_type: "marsai:security-reviewer"
model: "sonnet"
description: "Security review for [unit_id]"
prompt: |
## Security Review Request
**Unit ID:** [unit_id]
**Base SHA:** [base_sha]
**Head SHA:** [head_sha]
[implementation_summary]
[requirements]
[shared_context.diff]
[IF preanalysis_state.context["marsai:security-reviewer"] exists: INSERT it]
- Authentication and authorization
- Input validation
- SQL injection, XSS, CSRF
- Sensitive data handling
- OWASP Top 10 risks
**Standards have been pre-fetched by the orchestrator. Do NOT WebFetch — use the context below.**
[shared_context.standards]
**Check ALL applicable security sections:**
- Secret Redaction Patterns (MANDATORY — credential leak prevention)
- SQL Safety (MANDATORY — parameterized queries, injection prevention)
- HTTP Security Headers (MANDATORY — X-Content-Type-Options, X-Frame-Options)
- Rate Limiting (MANDATORY — if API endpoints changed)
- CORS Configuration (MANDATORY — if middleware changed)
| Severity | Description | File:Line | OWASP Category | Recommendation |
|----------|-------------|-----------|----------------|----------------|
| [CRITICAL/HIGH/MEDIUM/LOW] | [issue] | [location] | [A01-A10] | [fix] |
| Standard Section | Status | Evidence |
|-----------------|--------|----------|
| Secret Redaction | ✅/❌/N/A | [file:line] |
| SQL Safety | ✅/❌/N/A | [file:line] |
| HTTP Security Headers | ✅/❌/N/A | [file:line] |
| Rate Limiting | ✅/❌/N/A | [file:line] |
| CORS Configuration | ✅/❌/N/A | [file:line] |
| Check | Status |
|-------|--------|
| Input validation | ✅/❌ |
| Auth checks | ✅/❌ |
| No hardcoded secrets | ✅/❌ |
Task:
subagent_type: "marsai:test-reviewer"
model: "sonnet"
description: "Test quality review for [unit_id]"
prompt: |
## Test Quality Review Request
**Unit ID:** [unit_id]
**Base SHA:** [base_sha]
**Head SHA:** [head_sha]
[implementation_summary]
[requirements]
[shared_context.diff]
[IF preanalysis_state.context["marsai:test-reviewer"] exists: INSERT it]
- Test coverage for business logic
- Edge case testing (empty, null, boundary)
- Error path coverage
- Test independence and isolation
- Assertion quality (not just "no error")
- Test anti-patterns (testing mock behavior)
| Severity | Description | File:Line | Recommendation |
|----------|-------------|-----------|----------------|
| [CRITICAL/HIGH/MEDIUM/LOW] | [issue] | [location] | [fix] |
| Test Type | Count | Coverage |
|-----------|-------|----------|
| Unit | [N] | [areas] |
| Integration | [N] | [areas] |
| E2E | [N] | [areas] |
Task:
subagent_type: "marsai:nil-safety-reviewer"
model: "sonnet"
description: "Nil/null safety review for [unit_id]"
prompt: |
## Nil-Safety Review Request
**Unit ID:** [unit_id]
**Base SHA:** [base_sha]
**Head SHA:** [head_sha]
**Languages:** [Go|TypeScript|both - detect from files]
[implementation_summary]
[requirements]
[shared_context.diff]
[IF preanalysis_state.context["marsai:nil-safety-reviewer"] exists: INSERT it]
- Nil/null pointer risks in changed code
- Missing nil guards before dereference
- Map access without ok check (Go)
- Type assertions without ok check (Go)
- Optional chaining misuse (TypeScript)
- Error-then-use patterns
| Severity | Description | File:Line | Recommendation |
|----------|-------------|-----------|----------------|
| [CRITICAL/HIGH/MEDIUM/LOW] | [issue] | [location] | [fix] |
[For each risk: Source → Propagation → Dereference point]
Task:
subagent_type: "marsai:consequences-reviewer"
model: "sonnet"
description: "Consequences review for [unit_id]"
prompt: |
## Consequences Review Request
**Unit ID:** [unit_id]
**Base SHA:** [base_sha]
**Head SHA:** [head_sha]
[implementation_summary]
[requirements]
[shared_context.diff]
[IF preanalysis_state.context["marsai:consequences-reviewer"] exists: INSERT it]
- Caller chain impact analysis
- Consumer contract integrity
- Shared state and configuration consequences
- Type and interface propagation
- Error handling chain consequences
- Database/schema ripple effects
| Severity | Description | File:Line | Recommendation |
|----------|-------------|-----------|----------------|
| [CRITICAL/HIGH/MEDIUM/LOW] | [issue] | [location] | [fix] |
[For each changed symbol: callers found, consumers found, impact status]
Task:
subagent_type: "marsai:dead-code-reviewer"
model: "sonnet"
description: "Dead code review for [unit_id]"
prompt: |
## Dead Code Review Request
**Unit ID:** [unit_id]
**Base SHA:** [base_sha]
**Head SHA:** [head_sha]
[implementation_summary]
[requirements]
[shared_context.diff]
[IF preanalysis_state.context["marsai:dead-code-reviewer"] exists: INSERT it]
- Code that became orphaned/dead as a consequence of the changes
- MarsAI 1: Dead code within the changed files
- MarsAI 2: First-derivative dependents now orphaned (helpers, validators, converters)
- MarsAI 3: Transitive cascade orphans (entire packages, utility chains)
- Test infrastructure that only served removed code
- Orphaned validation/security logic (CRITICAL in financial systems)
| Severity | Description | File:Line | Recommendation |
|----------|-------------|-----------|----------------|
| [CRITICAL/HIGH/MEDIUM/LOW] | [issue] | [location] | [fix] |
[For each orphan: What happened, caller count evidence, ring, cascade check]
Step 4: Wait for All Reviewers and Parse Output
IF review_state.slicing.enabled == true:
→ Results already merged and deduped in Step 3-S-Merge
→ review_state.reviewers and review_state.aggregated_issues are populated
→ Include cross-cutting issues in report:
IF review_state.slicing.cross_cutting_issues.length > 0:
→ Add section to consolidated output:
"### Cross-Cutting Concerns (found across multiple slices)"
FOR EACH cross_cutting_issue:
→ "[severity] [description] at [file:line]
Found in slices: [slice_a], [slice_b]
Flagged by: [reviewer_a], [reviewer_b]
This may indicate an architectural issue."
→ Skip to verdict aggregation below
IF review_state.slicing.enabled == false (STANDARD MODE):
→ Wait for all 7 Task calls to complete.
For each reviewer:
1. Extract VERDICT (PASS/FAIL)
2. Extract Issues Found table
3. Categorize issues by severity
review_state.reviewers.code_reviewer = {
verdict: [PASS/FAIL],
issues: [parsed issues]
}
// ... same for other reviewers
Aggregate all issues by severity:
review_state.aggregated_issues.critical = [all critical from all reviewers]
review_state.aggregated_issues.high = [all high from all reviewers]
// ... etc
Step 5: Handle Results by Severity
Count blocking issues:
blocking_count = critical.length + high.length + medium.length
IF blocking_count == 0:
→ All reviewers PASS
→ Proceed to Step 8 (Success)
IF blocking_count > 0:
→ review_state.iterations += 1
→ IF iterations >= max_iterations: Go to Step 9 (Escalate)
→ Go to Step 6 (Dispatch Fixes)
Step 6: Dispatch Fixes to Implementation Agent
⛔ CRITICAL: You are an ORCHESTRATOR. You CANNOT edit source files directly.
You MUST dispatch the implementation agent to fix ALL review issues.
Orchestrator Boundaries (HARD GATE)
See dev-team/skills/shared-patterns/standards-boundary-enforcement.md for core enforcement rules.
Key prohibition: Edit/Write/Create on source files is FORBIDDEN. Always dispatch agent.
If you catch yourself about to use Edit/Write/Create on source files → STOP. Dispatch agent.
Dispatch Implementation Agent
Task:
subagent_type: "[implementation_agent from Gate 0]"
description: "Fix review issues for [unit_id]"
prompt: |
⛔ FIX REQUIRED - Code Review Issues Found
- **Unit ID:** [unit_id]
- **Iteration:** [iterations] of [max_iterations]
[list critical issues with file:line and recommendation]
[list high issues]
[list medium issues]
1. Fix ALL Critical, High, and Medium issues
2. Run tests to verify fixes
3. Commit fixes with descriptive message
4. Return list of fixed issues with evidence
Add TODO/FIXME comments:
- Low: `// TODO(review): [Issue] - [reviewer] on [date]`
- Cosmetic: `// FIXME(nitpick): [Issue] - [reviewer] on [date]`
Anti-Rationalization for Direct Editing
See shared-patterns/orchestrator-direct-editing-anti-rationalization.md for complete anti-rationalization table.
Applies to: Step 6 (Fix dispatch after MarsAI reviewers) & Step 7.5.3 (Fix dispatch after CodeRabbit)
Step 7: Re-Run All Reviewers After Fixes
After fixes committed:
1. Get new HEAD_SHA
2. Go back to Step 3 (dispatch all 7 reviewers again)
⛔ CRITICAL: Always re-run ALL 7 reviewers after fixes.
Do NOT cherry-pick reviewers.
Step 7.5: CodeRabbit CLI Validation (Per-Subtask/Task)
⛔ NEW APPROACH: CodeRabbit validates EACH subtask/task as it completes, accumulating findings to a file.
CodeRabbit Integration Overview
┌─────────────────────────────────────────────────────────────────┐
│ CODERABBIT PER-UNIT VALIDATION FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ DURING REVIEW (after each subtask/task MarsAI reviewers pass): │
│ 1. Run CodeRabbit for that unit's files │
│ 2. Append findings to .coderabbit-findings.md │
│ 3. Continue to next unit │
│ │
│ BEFORE COMMIT (Step 8): │
│ 1. Display accumulated .coderabbit-findings.md │
│ 2. User decides: fix issues OR acknowledge and proceed │
│ │
│ BENEFITS: │
│ • Catches issues close to when code was written │
│ • Smaller scope = faster reviews (7-30 min per unit) │
│ • Issues isolated to specific units, easier to fix │
│ • Accumulated file provides audit trail │
│ │
└─────────────────────────────────────────────────────────────────┘
Rate Limits (Official - per developer per repository per hour)
| Limit Type | Value | Notes |
|---|
| Files reviewed | 200 files/hour | Per review |
| Reviews | 3 back-to-back, then 4/hour | 7 reviews possible in first hour |
| Conversations | 25 back-to-back, then 50/hour | For follow-up questions |
⏱️ TIMING: Each CodeRabbit review takes 7-30+ minutes depending on scope.
Run in background and check periodically for completion.
Common Commands Reference
CodeRabbit Installation Check:
which coderabbit || which cr
Used in Step 7.5.1 and after installation to verify CLI availability.
⚠️ PREREQUISITES & ENVIRONMENT REQUIREMENTS
Before attempting Step 7.5, verify your environment supports the required operations:
| Requirement | Local Dev | CI/CD | Containerized | Remote/SSH |
|---|
curl | sh install | ✅ Yes | ⚠️ May require elevated permissions | ❌ Often blocked | ⚠️ Depends on config |
Browser auth (coderabbit auth login) | ✅ Yes | ❌ No browser | ❌ No browser | ❌ No browser |
Write to $HOME/.coderabbit/ | ✅ Yes | ⚠️ Ephemeral | ⚠️ Ephemeral | ✅ Usually |
Internet access to cli.coderabbit.ai | ✅ Yes | ⚠️ Check firewall | ⚠️ Check firewall | ⚠️ Check firewall |
⛔ HARD STOP CONDITIONS - Skip Step 7.5 if ANY apply:
- Running in containerized environment without persistent storage
- CI/CD pipeline without pre-installed CodeRabbit CLI
- Non-interactive environment (no TTY for browser auth)
- Network restrictions blocking
cli.coderabbit.ai
- Read-only filesystem
Environment-Specific Guidance
Local Development (RECOMMENDED)
Standard flow works: curl | sh install + browser authentication.
CI/CD Pipelines
Option A: Pre-install in CI image
# Add to your CI Dockerfile
RUN curl -fsSL https://cli.coderabbit.ai/install.sh | sh
Option B: Use API token authentication (headless)
export CODERABBIT_API_TOKEN="your-api-token"
coderabbit auth login --token "$CODERABBIT_API_TOKEN"
Option C: Skip CodeRabbit in CI, run locally
export SKIP_CODERABBIT_REVIEW=true
Containerized/Docker Environments
docker run -v ~/.coderabbit:/root/.coderabbit ...
docker run -e CODERABBIT_API_TOKEN="..." ...
Non-Interactive/Headless Authentication
coderabbit auth login --token "cr_xxxxxxxxxxxxx"
Step 7.5 Flow Logic
┌─────────────────────────────────────────────────────────────────┐
│ ✅ ALL 3 RING REVIEWERS PASSED │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Checking CodeRabbit CLI availability... │
│ │
│ CodeRabbit provides additional AI-powered code review that │
│ catches race conditions, memory leaks, security vulnerabilities,│
│ and edge cases that may complement MarsAI reviewers. │
│ │
└─────────────────────────────────────────────────────────────────┘
⛔ HARD GATE: CodeRabbit Execution Rules (NON-NEGOTIABLE)
| Scenario | Rule | Action |
|---|
| Installed & authenticated | MANDATORY - CANNOT skip | Run CodeRabbit review, no prompt |
| Not installed | MUST ask user about installation | Present installation option |
| User declines installation | Optional - can proceed | Skip and continue to Step 8 |
Why this distinction:
- If CodeRabbit IS installed → User has committed to using it → MUST run
- If CodeRabbit is NOT installed → User choice to add it → MUST ask, but can decline
FLOW:
1. Run CodeRabbit Installation Check
2. IF installed AND authenticated → Run CodeRabbit (MANDATORY, NO prompt, CANNOT skip)
3. IF installed BUT NOT authenticated → Guide authentication (REQUIRED before proceeding)
4. IF NOT installed → MUST ask user about installation (REQUIRED prompt)
5. IF user declines installation → Skip CodeRabbit, proceed to Step 8 (only valid skip path)
Anti-Rationalization for CodeRabbit Execution
| Rationalization | Why It's WRONG | Required Action |
|---|
| "CodeRabbit is optional, I'll skip it" | If installed, it's MANDATORY. Optional only means installation is optional. | Run CodeRabbit if installed |
| "MarsAI reviewers passed, that's enough" | Different tools catch different issues. CodeRabbit complements MarsAI. | Run CodeRabbit if installed |
| "User didn't ask for CodeRabbit" | User installed it. Installation = consent to mandatory execution. | Run CodeRabbit if installed |
| "Takes too long, skip this time" | Time is irrelevant. Installed = mandatory. | Run CodeRabbit if installed |
| "I'll just proceed without asking about install" | MUST ask every user if they want to install. No silent skips. | Ask user about installation |
Step 7.5.1: Check CodeRabbit Installation
Run the CodeRabbit Installation Check command.
IF INSTALLED AND AUTHENTICATED → MANDATORY EXECUTION (CANNOT SKIP):
┌─────────────────────────────────────────────────────────────────┐
│ ✅ CodeRabbit CLI detected - MANDATORY EXECUTION │
├─────────────────────────────────────────────────────────────────┤
│ │
│ CodeRabbit CLI is installed and authenticated. │
│ │
│ ⛔ CodeRabbit review is MANDATORY when installed. │
│ This step CANNOT be skipped. Proceeding automatically... │
│ │
└─────────────────────────────────────────────────────────────────┘
→ Proceed directly to Step 7.5.2 (Run CodeRabbit Review) - NO user prompt, NO skip option
IF NOT INSTALLED → MUST ASK USER (REQUIRED PROMPT):
⛔ You MUST present this prompt to the user. Silent skips are FORBIDDEN.
┌─────────────────────────────────────────────────────────────────┐
│ ⚠️ CodeRabbit CLI not found - INSTALLATION PROMPT REQUIRED │
├─────────────────────────────────────────────────────────────────┤
│ │
│ CodeRabbit CLI is not installed on your system. │
│ │
│ CodeRabbit provides additional AI-powered review that catches: │
│ • Race conditions and concurrency issues │
│ • Memory leaks and resource management │
│ • Security vulnerabilities │
│ • Edge cases missed by other reviewers │
│ │
│ ⛔ You MUST choose one of the following options: │
│ │
│ (a) Yes, install CodeRabbit CLI (I'll guide you) │
│ (b) No, skip CodeRabbit and proceed to Gate 5 │
│ │
│ ⚠️ ENVIRONMENT CHECK: │
│ • Interactive terminal with browser? → Standard install │
│ • CI/headless? → Requires API token auth │
│ • Container? → See Environment-Specific Guidance above │
│ │
└─────────────────────────────────────────────────────────────────┘
If user selects (a) Yes, install:
→ Proceed to Installation Flow below
If user selects (b) No, skip:
→ Record: "CodeRabbit review: SKIPPED (not installed, user declined installation)"
→ Proceed to Step 8 (Success Output)
→ This is the ONLY valid path to skip CodeRabbit
Step 7.5.1a: CodeRabbit Installation Flow
┌─────────────────────────────────────────────────────────────────┐
│ 📦 INSTALLING CODERABBIT CLI │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ⚠️ ENVIRONMENT CHECK FIRST: │
│ │
│ This installation requires: │
│ • curl command available │
│ • Write access to $HOME or /usr/local/bin │
│ • Internet access to cli.coderabbit.ai │
│ • Non-containerized environment (or persistent storage) │
│ │
│ If in CI/container, see "Environment-Specific Guidance" above. │
│ │
└─────────────────────────────────────────────────────────────────┘
Check environment before proceeding:
curl --version && echo "curl: OK" || echo "curl: MISSING"
test -w "$HOME" && echo "HOME writable: OK" || echo "HOME writable: NO"
curl -sI https://cli.coderabbit.ai | head -1 | grep -q "200\|301\|302" && echo "Network: OK" || echo "Network: BLOCKED"
If prerequisites pass, install:
┌─────────────────────────────────────────────────────────────────┐
│ 📦 Step 1: Installing CodeRabbit CLI... │
└─────────────────────────────────────────────────────────────────┘
curl -fsSL https://cli.coderabbit.ai/install.sh | sh
After installation, verify: Run the CodeRabbit Installation Check command.
If installation successful:
┌─────────────────────────────────────────────────────────────────┐
│ ✅ CodeRabbit CLI installed successfully! │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Step 2: Authentication required │
│ │
│ Choose your authentication method: │
│ │
│ (a) Browser login (interactive - opens browser) │
│ → Best for: Local development with GUI │
│ → Command: coderabbit auth login │
│ │
│ (b) API token (headless - no browser needed) │
│ → Best for: CI/CD, containers, SSH sessions │
│ → Get token: https://app.coderabbit.ai/settings/api-tokens│
│ → Command: coderabbit auth login --token "cr_xxx" │
│ │
│ (c) Skip authentication and CodeRabbit review │
│ │
│ Note: Free tier allows 1 review/hour. │
│ Paid plans get enhanced reviews + higher limits. │
│ │
└─────────────────────────────────────────────────────────────────┘
If user selects (a) Browser login:
coderabbit auth login
If user selects (b) API token:
coderabbit auth login --token "cr_xxxxxxxxxxxxx"
After authentication:
┌─────────────────────────────────────────────────────────────────┐
│ ✅ CodeRabbit CLI ready! │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Installation: Complete │
│ Authentication: Complete │
│ │
│ Proceeding to CodeRabbit review... │
│ │
└─────────────────────────────────────────────────────────────────┘
→ Proceed to Step 7.5.2 (Run CodeRabbit Review)
If installation failed:
┌─────────────────────────────────────────────────────────────────┐
│ ❌ CodeRabbit CLI installation failed │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Error: [error message from curl/sh] │
│ │
│ Troubleshooting: │
│ • Check internet connection │
│ • Try manual install: https://docs.coderabbit.ai/cli/overview │
│ • macOS/Linux only (Windows not supported yet) │
│ │
│ Would you like to: │
│ (a) Retry installation │
│ (b) Skip CodeRabbit and proceed to Gate 5 │
│ │
└─────────────────────────────────────────────────────────────────┘
Step 7.5.2: Run CodeRabbit Review
⛔ GRANULAR VALIDATION: CodeRabbit MUST validate at the most granular level available.
DETERMINE VALIDATION SCOPE:
1. Check if current work has subtasks (from gate0_handoff or implementation context)
2. IF subtasks exist → Validate EACH SUBTASK separately
3. IF no subtasks → Validate the TASK as a whole
WHY GRANULAR VALIDATION:
- Subtask-level validation catches issues early
- Easier to pinpoint which subtask introduced problems
- Prevents "works for task A, breaks task B" scenarios
- Enables incremental fixes without re-running entire review
Step 7.5.2a: Determine Validation Scope
validation_scope = {
mode: null, // "subtask" or "task"
units: [], // list of {id, files, commits} to validate
current_index: 0
}
IF gate0_handoff.subtasks exists AND gate0_handoff.subtasks.length > 0:
→ validation_scope.mode = "subtask"
→ FOR EACH subtask in gate0_handoff.subtasks:
→ Get files changed by this subtask (from commits or file mapping)
→ Add to validation_scope.units: {
id: subtask.id,
name: subtask.name,
files: [files touched by this subtask],
base_sha: [sha before subtask],
head_sha: [sha after subtask]
}
Display:
┌─────────────────────────────────────────────────────────────────┐
│ 📋 CODERABBIT VALIDATION MODE: SUBTASK-LEVEL │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Detected [N] subtasks. Will validate each separately: │
│ │
│ 1. [subtask-1-id]: [subtask-1-name] │
│ Files: [file1.go, file2.go] │
│ │
│ 2. [subtask-2-id]: [subtask-2-name] │
│ Files: [file3.go, file4.go] │
│ │
│ ... (up to N subtasks) │
│ │
└─────────────────────────────────────────────────────────────────┘
ELSE:
→ validation_scope.mode = "task"
→ Add single unit: {
id: unit_id,
name: implementation_summary,
files: implementation_files,
base_sha: base_sha,
head_sha: head_sha
}
Display:
┌─────────────────────────────────────────────────────────────────┐
│ 📋 CODERABBIT VALIDATION MODE: TASK-LEVEL │
├─────────────────────────────────────────────────────────────────┤
│ │
│ No subtasks detected. Validating entire task: │
│ │
│ Task: [unit_id] │
│ Files: [N] files changed │
│ │
└─────────────────────────────────────────────────────────────────┘
Step 7.5.2b: Run CodeRabbit for Each Validation Unit
coderabbit_results = {
overall_status: "PASS", // PASS only if ALL units pass
units: []
}
FOR EACH unit IN validation_scope.units:
Display:
┌─────────────────────────────────────────────────────────────────┐
│ 🔍 VALIDATING: [unit.id] ([current]/[total]) │
├─────────────────────────────────────────────────────────────────┤
│ Name: [unit.name] │
│ Files: [unit.files.join(", ")] │
└─────────────────────────────────────────────────────────────────┘
coderabbit --prompt-only --type uncommitted --base [base_branch]
coderabbit --prompt-only --type uncommitted --base-commit [unit.base_sha]
Parse output and record:
unit_result = {
id: unit.id,
status: "PASS" | "ISSUES_FOUND",
issues: {
critical: [list],
high: [list],
medium: [list],
low: [list]
}
}
coderabbit_results.units.push(unit_result)
IF unit_result.issues.critical.length > 0 OR unit_result.issues.high.length > 0:
→ coderabbit_results.overall_status = "ISSUES_FOUND"
─────────────────────────────────────────────────────────────────
⛔ MANDATORY: APPEND FINDINGS TO .coderabbit-findings.md
─────────────────────────────────────────────────────────────────
After EACH unit validation, append results to findings file:
IF .coderabbit-findings.md does NOT exist:
→ Create file with header (see "Findings File Format" below)
APPEND to .coderabbit-findings.md:
Unit: [unit.id] - [unit.name]
Validated: [timestamp]
Status: [PASS | ISSUES_FOUND]
Files: [unit.files.join(", ")]
Issues Found
| # | Severity | Description | File:Line | Recommendation |
|---|
| 1 | [severity] | [description] | [file:line] | [recommendation] |
| ... | ... | ... | ... | ... |
This ensures ALL findings are accumulated for review before commit.
AFTER ALL UNITS VALIDATED:
Display summary:
┌─────────────────────────────────────────────────────────────────┐
│ 📊 CODERABBIT VALIDATION SUMMARY │
├─────────────────────────────────────────────────────────────────┤
│ Mode: [SUBTASK-LEVEL | TASK-LEVEL] │
│ Units Validated: [N] │
│ Overall Status: [PASS | ISSUES_FOUND] │
│ │
│ Per-Unit Results: │
│ ┌──────────────┬────────────┬──────┬──────┬────────┬─────┐ │
│ │ Unit ID │ Status │ Crit │ High │ Medium │ Low │ │
│ ├──────────────┼────────────┼──────┼──────┼────────┼─────┤ │
│ │ [subtask-1] │ ✅ PASS │ 0 │ 0 │ 0 │ 1 │ │
│ │ [subtask-2] │ ❌ ISSUES │ 1 │ 2 │ 0 │ 0 │ │
│ └──────────────┴────────────┴──────┴──────┴────────┴─────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Parse CodeRabbit output for:
- Critical issues
- High severity issues
- Security vulnerabilities
- Performance concerns
Findings File Format (.coderabbit-findings.md)
This file accumulates ALL CodeRabbit findings across all validated units.
# CodeRabbit Findings
**Generated:** [initial timestamp]
**Last Updated:** [latest timestamp]
**Total Units Validated:** [N]
**Overall Status:** [PASS | ISSUES_FOUND]
## Summary
| Severity | Count | Status |
|----------|-------|--------|
| Critical | [N] | [N pending / N fixed] |
| High | [N] | [N pending / N fixed] |
| Medium | [N] | [N pending / N fixed] |
| Low | [N] | [N pending / N fixed] |
---
## Unit: [subtask-1-id] - [subtask-1-name]
**Validated:** [timestamp]
**Status:** [PASS | ISSUES_FOUND]
**Files:** [file1.go, file2.go]
### Issues Found
| # | Severity | Description | File:Line | Recommendation | Status |
|---|----------|-------------|-----------|----------------|--------|
| 1 | CRITICAL | Race condition in handler | handler.go:45 | Use sync.Mutex | PENDING |
| 2 | HIGH | Unchecked error return | repo.go:123 | Handle error | PENDING |
---
## Unit: [subtask-2-id] - [subtask-2-name]
**Validated:** [timestamp]
**Status:** PASS
**Files:** [file3.go]
### Issues Found
_No issues found._
---
[... additional units ...]
File Location: Project root (.coderabbit-findings.md)
Lifecycle:
- Created when first CodeRabbit validation runs
- Appended after each unit validation
- Displayed before commit (Step 8)
- User decides: fix issues or acknowledge and proceed
- After commit, file can be deleted or kept for audit
Step 7.5.3: Handle CodeRabbit Findings
⛔ CRITICAL: You are an ORCHESTRATOR. You CANNOT edit source files directly.
You MUST dispatch the implementation agent to fix issues.
⛔ GRANULAR FIX DISPATCH: Fixes MUST be dispatched per-unit (subtask or task).
IF coderabbit_results.overall_status == "ISSUES_FOUND":
→ FIRST: Display EACH issue in detail (REQUIRED before any action):
┌─────────────────────────────────────────────────────────────────┐
│ ⚠️ CODERABBIT ISSUES FOUND - DETAILED DESCRIPTION │
├─────────────────────────────────────────────────────────────────┤
│ │
│ UNIT: [subtask-1] - [subtask name] │
│ ───────────────────────────────────────────────────────────────│
│ Issue #1 [CRITICAL] │
│ Description: Race condition in concurrent request handler │
│ File: src/handler.go:45 │
│ Code Context: │
│ 43 | func (h *Handler) Process(ctx context.Context) { │
│ 44 | h.counter++ // ← NOT THREAD-SAFE │
│ 45 | data := h.sharedMap[key] │
│ Why it matters: Multiple goroutines can corrupt shared state │
│ Recommendation: Use sync.Mutex or atomic operations │
│ │
│ Issue #2 [HIGH] │
│ Description: Unchecked error return from database query │
│ File: src/repo.go:123 │
│ Code Context: │
│ 121 | func (r *Repo) GetUser(id string) (*User, error) { │
│ 122 | result, _ := r.db.Query(query, id) // ← IGNORED │
│ 123 | return parseUser(result), nil │
│ Why it matters: Silent failures can cause data corruption │
│ Recommendation: Check and handle the error properly │
│ │
│ UNIT: [subtask-2] - [subtask name] │
│ ───────────────────────────────────────────────────────────────│
│ Issue #3 [HIGH] │
│ Description: SQL injection vulnerability │
│ File: src/query.go:89 │
│ Code Context: │
│ 87 | func BuildQuery(userInput string) string { │
│ 88 | return fmt.Sprintf("SELECT * FROM users WHERE │
│ 89 | name = '%s'", userInput) // ← INJECTABLE │
│ Why it matters: Attacker can execute arbitrary SQL │
│ Recommendation: Use parameterized queries │
│ │
└─────────────────────────────────────────────────────────────────┘
→ THEN: Ask user for action:
"CodeRabbit found [N] issues in [M] units. What would you like to do?"
(a) Fix all issues - dispatch implementation agent per unit
(b) Proceed to Gate 5 (acknowledge risk)
(c) Review findings in detail (show code context)
IF user selects (a) Fix issues:
→ ⛔ DO NOT edit files directly
→ FOR EACH unit WITH issues (validation_scope.units where status == "ISSUES_FOUND"):
Display:
┌─────────────────────────────────────────────────────────────────┐
│ 🔧 DISPATCHING FIX: [unit.id] ([current]/[total with issues]) │
├─────────────────────────────────────────────────────────────────┤
│ Unit: [unit.name] │
│ Critical Issues: [N] │
│ High Issues: [N] │
└─────────────────────────────────────────────────────────────────┘
→ DISPATCH implementation agent with unit-specific findings:
Task:
subagent_type: "[same agent used in Gate 0]"
description: "Fix CodeRabbit issues for [unit.id]"
prompt: |
## CodeRabbit Issues to Fix - [unit.id]
**Scope:** This fix is for [subtask/task]: [unit.name]
**Files in Scope:** [unit.files.join(", ")]
The following issues were found by CodeRabbit CLI external review
for THIS SPECIFIC [subtask/task].
⚠️ IMPORTANT: Only fix issues in files belonging to this unit:
[unit.files list]
### Critical Issues
[list from unit.issues.critical]
### High Issues
[list from unit.issues.high]
## Requirements
1. Fix each issue following MarsAI Standards
2. Only modify files in scope: [unit.files]
3. Run tests to verify fixes don't break functionality
4. Commit fixes with message referencing unit: "fix([unit.id]): [description]"
→ Wait for agent to complete
→ Record fix result for this unit
→ VALIDATE EACH ISSUE INDIVIDUALLY:
┌─────────────────────────────────────────────────────────────────┐
│ 🔍 VALIDATING FIXES FOR: [unit.id] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Each issue MUST be validated individually: │
│ │
│ Issue #1: [issue description] │
│ File: [file:line] │
│ Severity: CRITICAL │
│ Fix Applied: [description of fix] │
│ Validation: ✅ RESOLVED / ❌ NOT RESOLVED │
│ Evidence: [code snippet or test result] │
│ │
│ Issue #2: [issue description] │
│ File: [file:line] │
│ Severity: HIGH │
│ Fix Applied: [description of fix] │
│ Validation: ✅ RESOLVED / ❌ NOT RESOLVED │
│ Evidence: [code snippet or test result] │
│ │
│ ... (repeat for ALL issues) │
│ │
└─────────────────────────────────────────────────────────────────┘
→ IF any issue NOT RESOLVED:
→ Identify the correct agent for re-dispatch:
- Check gate0_handoff.implementation_agent (if available)
- OR infer from file type:
- *.ts files (backend) → marsai:backend-engineer-typescript
- *.ts/*.tsx files (frontend) → marsai:frontend-engineer
- *.yaml/*.yml (infra) → marsai:devops-engineer
→ Re-dispatch ONLY unresolved issues to the correct agent:
Task:
subagent_type: "[correct agent based on file type or gate0_handoff]"
description: "Retry fix for unresolved issues in [unit.id]"
prompt: |
## RETRY: Unresolved CodeRabbit Issues - [unit.id]
Previous fix attempt did NOT resolve these issues.
This is attempt [N] of 2 maximum.
### Unresolved Issues (MUST FIX)
| # | Severity | Description | File:Line | Previous Attempt | Why It Failed |
|---|----------|-------------|-----------|------------------|---------------|
| [issue.id] | [severity] | [description] | [file:line] | [what was tried] | [why not resolved] |
### Requirements
1. Review the previous fix attempt and understand why it failed
2. Apply a different/better solution
3. Verify the fix resolves the issue
4. Run relevant tests
5. Commit with message: "fix([unit.id]): retry [issue description]"
→ Max 2 fix attempts per issue
→ IF issue still NOT RESOLVED after 2 attempts:
→ Mark as UNRESOLVED_ESCALATE
→ Add to escalation report for manual review
→ Record per-issue validation results:
unit_validation = {
id: unit.id,
issues_validated: [
{
issue_id: 1,
description: "[issue]",
severity: "CRITICAL",
file: "[file:line]",
fix_applied: "[description]",
status: "RESOLVED" | "NOT_RESOLVED",
evidence: "[snippet or test]",
attempts: 1
},
...
],
all_resolved: true | false
}
→ AFTER ALL UNITS FIXED:
Display:
┌─────────────────────────────────────────────────────────────────┐
│ ✅ FIX DISPATCH COMPLETE │
├─────────────────────────────────────────────────────────────────┤
│ Units Fixed: [N] / [total with issues] │
│ Total Issues Validated: [N] │
│ Issues Resolved: [N] / [N] │
│ │
│ Per-Unit Fix Status: │
│ ┌──────────────┬────────────┬───────────────────────┐ │
│ │ Unit ID │ Status │ Commit │ │
│ ├──────────────┼────────────┼───────────────────────┤ │
│ │ [subtask-1] │ ✅ FIXED │ abc123 │ │
│ │ [subtask-2] │ ✅ FIXED │ def456 │ │
│ └──────────────┴────────────┴───────────────────────┘ │
│ │
│ Issue-Level Validation Details: │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ UNIT: [subtask-1] │ │
│ ├──────────────────────────────────────────────────────────┤ │
│ │ #1 [CRITICAL] Race condition in handler │ │
│ │ File: src/handler.go:45 │ │
│ │ Fix: Added mutex lock │ │
│ │ Status: ✅ RESOLVED │ │
│ │ Evidence: Test race_test.go passes │ │
│ ├──────────────────────────────────────────────────────────┤ │
│ │ #2 [HIGH] Unchecked error return │ │
│ │ File: src/handler.go:67 │ │
│ │ Fix: Added error check with proper handling │ │
│ │ Status: ✅ RESOLVED │ │
│ │ Evidence: Error path verified in unit test │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
LEGACY FLOW (when validation_scope.mode == "task"):
IF CodeRabbit found CRITICAL or HIGH issues:
→ Display findings to user
→ Ask: "CodeRabbit found [N] critical/high issues. Fix now or proceed anyway?"
(a) Fix issues - dispatch to implementation agent
(b) Proceed to Gate 5 (acknowledge risk)
(c) Review findings in detail
IF user selects (a) Fix issues:
→ ⛔ DO NOT edit files directly
→ DISPATCH implementation agent with CodeRabbit findings:
Task:
subagent_type: "[same agent used in Gate 0]"
description: "Fix CodeRabbit issues for [unit_id]"
prompt: |
## CodeRabbit Issues to Fix
The following issues were found by CodeRabbit CLI external review.
Fix ALL Critical and High severity issues.
### Critical Issues
[list from CodeRabbit output]
### High Issues
[list from CodeRabbit output]
## Requirements
1. Fix each issue following MarsAI Standards
2. Run tests to verify fixes don't break functionality
3. Commit fixes with descriptive message
→ After agent completes, re-run CodeRabbit: `coderabbit --prompt-only`
→ If CodeRabbit issues remain, repeat fix cycle (max 2 iterations for CodeRabbit)
→ ⛔ AFTER CodeRabbit passes, MUST re-run MarsAI reviewers:
┌─────────────────────────────────────────────────────────────────┐
│ 🔄 RE-RUNNING RING REVIEWERS AFTER CODERABBIT FIXES │
├─────────────────────────────────────────────────────────────────┤
│ │
│ CodeRabbit fixes may have introduced new issues detectable by │
│ MarsAI reviewers. Re-validation is MANDATORY before Gate 5. │
│ │
└─────────────────────────────────────────────────────────────────┘
Step 7.5.3a: Re-Run All 7 MarsAI Reviewers
─────────────────────────────────────────
1. Get new HEAD_SHA after CodeRabbit fixes
2. Dispatch all 7 reviewers in parallel (per Step 3):
- marsai:code-reviewer
- marsai:business-logic-reviewer
- marsai:security-reviewer
- marsai:test-reviewer
- marsai:nil-safety-reviewer
- marsai:consequences-reviewer
- marsai:dead-code-reviewer
3. Wait for all 7 to complete
Step 7.5.3b: Handle MarsAI Reviewer Results
─────────────────────────────────────────
IF all 7 MarsAI reviewers PASS:
→ Proceed to Step 8 (Success Output)
IF any MarsAI reviewer finds CRITICAL/HIGH/MEDIUM issues:
→ Increment ring_revalidation_iterations counter
→ IF ring_revalidation_iterations >= 2:
→ ESCALATE: "Max iterations reached after CodeRabbit fixes"
→ Go to Step 9 (Escalate)
→ DISPATCH implementation agent to fix MarsAI reviewer issues
→ After fixes committed:
→ Re-run CodeRabbit: `coderabbit --prompt-only`
→ IF CodeRabbit passes:
→ Re-run all 7 MarsAI reviewers (loop back to Step 7.5.3a)
→ IF CodeRabbit finds issues:
→ Fix CodeRabbit issues first, then re-run MarsAI reviewers
State tracking for CodeRabbit fix cycle:
```
coderabbit_fix_state = {
coderabbit_iterations: 0, // max 2 for CodeRabbit-only fixes
ring_revalidation_iterations: 0, // max 2 for MarsAI reviewer re-runs
total_max_iterations: 4 // absolute cap: 2 CR + 2 MarsAI
}
```
IF CodeRabbit found only MEDIUM/LOW issues:
→ Display summary
→ ⛔ DO NOT edit files directly to add TODOs
→ DISPATCH implementation agent to add TODO comments:
Task:
subagent_type: "[same agent used in Gate 0]"
description: "Add TODO comments for CodeRabbit findings"
prompt: |
Add TODO comments for these CodeRabbit findings:
[list MEDIUM/LOW issues with file:line]
Format: // TODO(coderabbit): [issue description]
→ After TODO comments added (code changed):
→ Re-run all 7 MarsAI reviewers (per Step 7.5.3a above)
→ IF MarsAI reviewers PASS: Proceed to Step 8
→ IF MarsAI reviewers find issues: Fix and re-run (max 2 iterations)
IF CodeRabbit found no issues:
→ Display: "✅ CodeRabbit review passed - no additional issues found"
→ No code changes made by CodeRabbit flow
→ Proceed directly to Step 8 (no MarsAI re-run needed)
Anti-Rationalization for Direct Editing
See shared-patterns/orchestrator-direct-editing-anti-rationalization.md - same table applies here.
Applies to: Step 6 (Fix dispatch after MarsAI reviewers) & Step 7.5.3 (Fix dispatch after CodeRabbit)
Step 7.5.4: CodeRabbit Results Summary
## CodeRabbit External Review
**Status:** [PASS|ISSUES_FOUND|SKIPPED]
**Validation Mode:** [SUBTASK-LEVEL|TASK-LEVEL]
**Units Validated:** [N]
**Total Issues Found:** [N]
**Issues Resolved:** [N]/[N]
### Per-Unit Validation Results
| Unit ID | Unit Name | Status | Critical | High | Medium | Low |
|---------|-----------|--------|----------|------|--------|-----|
| [subtask-1] | [name] | ✅ PASS | 0 | 0 | 0 | 1 |
| [subtask-2] | [name] | ✅ FIXED | 1→0 | 2→0 | 0 | 0 |
| [task-id] | [name] | ✅ PASS | 0 | 0 | 0 | 0 |
### Issues Found - Detailed Description (ALWAYS shown when issues exist)
#### Unit: [subtask-2]
| # | Severity | Description | File:Line | Code Context | Why It Matters | Recommendation |
|---|----------|-------------|-----------|--------------|----------------|----------------|
| 1 | CRITICAL | Race condition | handler.go:45 | `h.counter++` not thread-safe | Corrupts shared state | Use sync.Mutex |
| 2 | HIGH | Unchecked error | repo.go:123 | `result, _ := r.db.Query()` | Silent failures | Handle error |
| 3 | HIGH | SQL injection | query.go:89 | `fmt.Sprintf("...%s", input)` | Security breach | Parameterized query |
### Issue-Level Validation (REQUIRED after fixes are applied)
#### Unit: [subtask-2]
| # | Severity | Description | File:Line | Fix Applied | Status | Evidence |
|---|----------|-------------|-----------|-------------|--------|----------|
| 1 | CRITICAL | Race condition in concurrent handler | handler.go:45 | Added mutex lock around shared state | ✅ RESOLVED | race_test.go passes |
| 2 | HIGH | Unchecked error from DB query | repo.go:123 | Added error check with rollback | ✅ RESOLVED | Error path tested |
| 3 | HIGH | SQL injection vulnerability | query.go:89 | Used parameterized query | ✅ RESOLVED | Security test added |
#### Unit: [subtask-3] (if applicable)
| # | Severity | Description | File:Line | Fix Applied | Status | Evidence |
|---|----------|-------------|-----------|-------------|--------|----------|
| 1 | HIGH | Missing input validation | api.go:34 | Added validation middleware | ✅ RESOLVED | Fuzz test passes |
### Overall Summary by Severity
| Severity | Found | Resolved | Remaining | Action |
|----------|-------|----------|-----------|--------|
| Critical | [N] | [N] | 0 | Fixed |
| High | [N] | [N] | 0 | Fixed |
| Medium | [N] | [N] | 0 | TODO added |
| Low | [N] | - | [N] | TODO added |
CodeRabbit Skip Scenarios (ONLY VALID PATHS)
⛔ CodeRabbit can ONLY be skipped in these specific scenarios. Any other skip is a VIOLATION.
| Scenario | Record As | Next Step | Why Valid |
|---|
| CLI not installed, user explicitly declines install | SKIPPED (not installed, user declined) | Step 8 | User was asked and chose not to install |
| Installation failed after attempt, user skips | SKIPPED (installation failed) | Step 8 | Technical failure, user informed |
| Authentication failed after attempt, user skips | SKIPPED (auth failed) | Step 8 | Technical failure, user informed |
| Environment doesn't support (CI/container) | SKIPPED (unsupported environment) | Step 8 | Technical limitation |
⛔ INVALID SKIP SCENARIOS (FORBIDDEN):
| Invalid Scenario | Why FORBIDDEN | Required Action |
|---|
| CLI installed but "skipped for speed" | Installed = MANDATORY | Run CodeRabbit |
| CLI installed but "MarsAI reviewers passed" | Complementary tools, both required | Run CodeRabbit |
| CLI not installed, no prompt shown | MUST ask user about installation | Show installation prompt |
| Silent skip without user interaction | All skips require explicit user choice | Ask user |
⛔ NON-NEGOTIABLE: When CodeRabbit CLI IS installed and authenticated, execution is MANDATORY - it CANNOT be skipped under any circumstance.
Step 8: Display Accumulated Findings & Prepare Success Output
⛔ BEFORE generating success output, MUST display accumulated CodeRabbit findings.
Step 8.1: Display Accumulated CodeRabbit Findings
IF .coderabbit-findings.md exists:
┌─────────────────────────────────────────────────────────────────┐
│ 📋 CODERABBIT FINDINGS - ACCUMULATED DURING REVIEW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ The following issues were identified by CodeRabbit during the │
│ review process. Review before proceeding to commit. │
│ │
└─────────────────────────────────────────────────────────────────┘
→ Display contents of .coderabbit-findings.md
→ Show summary table:
┌─────────────────────────────────────────────────────────────────┐
│ 📊 CODERABBIT FINDINGS SUMMARY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ | Severity | Count | Status | │
│ |----------|-------|--------| │
│ | Critical | [N] | [pending/fixed] | │
│ | High | [N] | [pending/fixed] | │
│ | Medium | [N] | [pending/fixed] | │
│ | Low | [N] | [pending/fixed] | │
│ │
│ Total Issues: [N] | Fixed: [N] | Pending: [N] │
