unclejobs-ai/second-claude-code/review

Iron Law

mmbridge failure NEVER blocks the pipeline.

Red Flags

• "Looks good to me, no issues found" → STOP, because a review with zero findings is almost always a rubber stamp — at minimum the devil-advocate must attack 3 weak points.
• "I'll just run the quick preset, it's not important" → STOP, because preset selection determines reviewer coverage — match the preset to the content type, not the deadline.
• "The fact-checker verified it" → STOP, because fact-checker findings require source URLs — claims verified without citations are not verified at all.
• "One reviewer flagged it but the others didn't, so it's fine" → STOP, because severity conflicts use the higher severity with a noted disagreement — do not downgrade by vote count alone.
• "The location is somewhere in section 2" → STOP, because every finding must have a precise location (file:line for code, Section > Subsection for prose) — vague locations make findings unactionable.

Review

Run parallel reviewers with distinct roles, then merge their findings through a consensus gate.

When to Use

• Pre-publish content checks
• Strategy or plan validation
• Code review
• Any prompt like "review this" or "is this good?"

Reviewers

Presets

Security Preset

The security preset activates security-focused review with optional mmbridge security integration.

Its reviewer trio is identical to code, so a completed run cannot be told apart from a code run by reviewer names alone — what differentiates it is the mmbridge security external pass. Pass --preset security explicitly rather than expecting it to be inferred.

Internal reviewers (security mode)

• deep-reviewer (opus): Architecture security analysis — auth flows, data boundaries, privilege escalation paths
• fact-checker (sonnet): Known CVE checks, dependency vulnerability scanning, OWASP Top 10 verification
• structure-analyst (sonnet): Configuration audit — secrets exposure, permission models, environment isolation

MMBridge Security (via --external)

When --external is set and mmbridge is detected, mmbridge security runs in parallel with internal reviewers. Consistent with all other presets — --external is always opt-in.

mmbridge security --scope <scope> --json > /tmp/mmbridge-security-${RUN_ID}.json

Option passthrough:

• --scope: /scc:review --preset security --scope auth → mmbridge security --scope auth (default: all)
• --compliance: /scc:review --preset security --compliance GDPR,SOC2 → mmbridge security --compliance GDPR,SOC2

CWE Severity Mapping

mmbridge security uses CWE classification. Map to internal severities per references/mmbridge-integration.md § Severity Mapping.

Consensus gate

mmbridge security counts as 1 additional voter (same as --external for other presets):

• Without mmbridge: 2/3 pass (3 internal reviewers)
• With mmbridge: 3/4 pass (3 internal + 1 mmbridge; Math.round(0.67 * 4))

Academic Preset

The academic preset activates academic-focused review for research papers, theses, dissertations, and scholarly articles.

Internal reviewers (academic mode)

• deep-reviewer (opus): Argument structure review — thesis clarity, logical flow between sections, claim-evidence alignment, and overall coherence of the academic argument
• fact-checker (sonnet): Citation format validation — verifies references conform to the specified style (APA, MLA, or Chicago; default APA), checks for missing citations, inconsistent formatting, and broken cross-references
• structure-analyst (sonnet): Literature gap analysis — identifies missing key references in the field, undercited foundational works, and areas where additional literature support would strengthen the argument
• devil-advocate (sonnet): Methodology critique and evidence quality assessment — challenges research design choices, statistical validity, sample size adequacy, potential biases, and evaluates the strength and relevance of evidence presented

Option passthrough

• --citation-style: /scc:review --preset academic --citation-style APA (default: APA, accepts APA, MLA, Chicago)

Academic review focus areas

1. Citation format validation — Ensures all in-text citations and bibliography entries conform to the specified style guide (APA 7th, MLA 9th, or Chicago 17th edition). Flags missing DOIs, incorrect author formatting, and inconsistent date formats.
2. Methodology critique — Evaluates research design appropriateness, sample selection, data collection methods, analytical frameworks, and reproducibility. Flags unsupported methodological claims.
3. Literature gap analysis — Identifies missing seminal works, undercited subfields, over-reliance on a single source, and areas where the literature review fails to establish the research context.
4. Argument structure review — Assesses thesis statement clarity, logical progression from introduction through discussion, whether conclusions follow from presented evidence, and internal consistency across sections.
5. Evidence quality assessment — Rates evidence on relevance, recency, authority, and sufficiency. Flags anecdotal evidence presented as empirical, outdated sources in fast-moving fields, and claims lacking adequate support.

Consensus gate

Uses 4 reviewers (same gate logic as other presets):

• 3/4 pass (4 internal reviewers)
• With --external: 4/5 pass (4 internal + 1 external; Math.round(0.75 * 5))

Critic Output Format

Every reviewer MUST structure their output according to references/critic-schema.md. Each review must include:

1. Verdict — APPROVED | MINOR FIXES | NEEDS IMPROVEMENT | MUST FIX
2. Score — float 0.0 to 1.0 per the scale in references/critic-schema.md
3. Findings — structured table with severity, category, location, description, and suggestion for each issue
4. Summary — one sentence overall assessment

Unstructured prose output is not accepted. Each reviewer emits the ## Critic Output block defined in references/critic-schema.md.

Diversity and False Consensus

Same-session reviewers on the same model are not independent. For content, strategy, and full:

• at least 2 reviewers and 2 distinct models
• at least 1 external model when that runtime exists
• zero findings from every reviewer is a rubber stamp. The vote hook still emits APPROVED; the orchestrator must run an adversarial pass or name 3 weak points before treating silence as a pass.

Consensus Gate

Score-based consensus (primary gate):

• Pass condition: average score across reviewers >= 0.7 AND no Critical findings from any reviewer
• Any Critical finding forces MUST FIX regardless of average score or threshold count

Vote-count gate (secondary gate, used when score-based gate passes):

• 3-reviewer presets (content, strategy, code): pass with 2/3 approvals
• 4-reviewer preset (academic): pass with 3/4 approvals
• 2-reviewer preset (quick): pass only with 2/2 unanimous approval
• 5-reviewer preset (full): pass with 3/5 approvals (Math.round(0.67 * 5)). The hook uses Math.round, not ceil.
• With --external, the external result is one additional voter and the hook recomputes the requirement over

the larger total: 3/4 for 3-reviewer presets, 4/5 for academic, 3/3 for quick, and 4/6 for full.

Final verdicts: APPROVED, MINOR FIXES, NEEDS IMPROVEMENT, MUST FIX

• NEEDS IMPROVEMENT = threshold not met but no Critical findings (substantive rework needed)

Score tracking: store per-reviewer scores in the review aggregation block for cycle comparison. See references/consensus-gate.md for the aggregation format.

Severity Calibration

Three levels: Critical (ship-blocking), Major (significant gap), Minor (polish). See references/consensus-gate.md for detailed criteria and examples.

Workflow

1. Dispatch preset reviewers in parallel with independent context. Each reviewer receives ONLY the content to review and their role prompt — never another reviewer's findings.
2. Collect structured findings with severity levels.
3. Deduplicate overlapping findings (see Deduplication Rules below).
4. Apply the consensus gate and return a single report.

Deduplication Rules

See references/consensus-gate.md for the full deduplication protocol. Key rule: severity conflicts use the higher severity with a noted disagreement.

Output

Each finding MUST include all four fields: location, severity, description, and fix suggestion.

# Review Report
## Verdict: {APPROVED | MINOR FIXES | NEEDS IMPROVEMENT | MUST FIX}
Consensus: {X}/{Y}
 
## Score Aggregation
 
| Reviewer | Score | Verdict |
|----------|-------|---------|
| {reviewer-name} | {0.00} | {APPROVED \| MINOR FIXES \| NEEDS IMPROVEMENT \| MUST FIX} |
| **Average** | **{0.00}** | — |
 
## Findings
 
### Critical
-**[reviewer(s)]** `{file:line | Section > Subsection | paragraph N}` — {description with evidence} → **Fix:** {specific actionable suggestion}
 
### Major
-**[reviewer(s)]** `{location}` — {description} → **Fix:** {specific suggestion}
 
### Minor
-**[reviewer(s)]** `{location}` — {description} → **Fix:** {specific suggestion}

Format rules:

• Location must be precise enough to find the issue without re-reading the whole document. Use file:line for code, Section > Subsection or paragraph N for prose.
• Fix suggestion must be a concrete action ("Change X to Y", "Add Z after line N"), never vague ("improve this", "consider revising").
• If multiple reviewers flagged the same finding, list all in the [reviewer(s)] tag.

MMBridge Diff Visualization

When mmbridge is detected (see references/mmbridge-integration.md) and the review has completed, offer the user an annotated diff view.

When to Offer

• After the Review Report is generated
• Only for code and security presets (diff annotation is most useful for code)
• Do not offer for content, strategy, academic, or quick presets

Command

mmbridge diff --base-ref <base> > /tmp/mmbridge-diff-${RUN_ID}.md

• --base-ref: use the same base ref as the review (default: HEAD~1)
• --tool kimi: filter to show only findings from a specific tool (optional)

Output

Present the annotated diff to the user as supplementary output after the Review Report. The diff shows exactly which lines each finding maps to, making it easier to act on review feedback.

This is a display enhancement only — it does not affect the consensus gate or verdict.

Options