Unified Review

Table of Contents

• Quick Start
• When to Use
• Review Skill Selection Matrix
• Workflow
• 1. Analyze Repository Context
• 2. Select Review Skills
• 3. Execute Reviews
• 4. Integrate Findings
• Review Modes
• Auto-Detect (default))
• Focused Mode
• Full Review Mode
• Quality Gates
• Deliverables
• Executive Summary
• Domain-Specific Reports
• Integrated Action Plan
• Modular Architecture
• Exit Criteria

Unified Review Orchestration

Intelligently selects and executes appropriate review skills based on codebase analysis and context.

Quick Start

# Auto-detect and run appropriate reviews
/full-review

# Focus on specific areas
/full-review api          # API surface review
/full-review architecture # Architecture review
/full-review bugs         # Bug hunting
/full-review tests        # Test suite review
/full-review all          # Run all applicable skills

Verification: Run pytest -v to verify tests pass.

When To Use

• Starting a full code review
• Reviewing changes across multiple domains
• Need intelligent selection of review skills
• Want integrated reporting from multiple review types
• Before merging major feature branches

When NOT To Use

• Specific review type known
• use bug-review
• Test-review
• Architecture-only focus - use

architecture-review

• Specific review type known
• use bug-review

Review Skill Selection Matrix

Workflow

1. Analyze Repository Context

• Detect primary languages from extensions and manifests
• Analyze git status and diffs for change scope
• Identify project structure (monorepo, microservices, library)
• Detect build systems, testing frameworks, documentation

2. Select Review Skills

# Detection logic
if has_rust_files():
    schedule_skill("rust-review")
if has_api_changes():
    schedule_skill("api-review")
if has_test_files():
    schedule_skill("test-review")
if has_makefiles():
    schedule_skill("makefile-review")
if has_math_code():
    schedule_skill("math-review")
if has_architecture_changes():
    schedule_skill("architecture-review")
# Default
schedule_skill("bug-review")

Verification: Run pytest -v to verify tests pass.

3. Execute Reviews

Dispatch selected skills concurrently via the Agent tool. Use this mapping to resolve skill names to agent types:

Sub-agent isolation (required):

Dispatch ALL selected agents in a SINGLE parallel Agent tool call. Do not read or process any agent's output until ALL agents have returned their results. Reading the first result before the others are in anchors synthesis toward that perspective: each subsequent result gets evaluated against the first rather than independently. Collect all results, then synthesize once.

Rules:

• Never use skill names as agent types (e.g., pensive:math-review is NOT an agent)
• When pensive:code-reviewer covers multiple domains, dispatch once with combined scope
• For skills without dedicated agents, use general-purpose and instruct it to invoke the Skill tool
• Maintain consistent evidence logging across all agents
• Track progress via TodoWrite

4. Integrate Findings

• Consolidate findings across domains
• Identify cross-domain patterns
• Prioritize by impact and effort
• Generate unified action plan

Deferred capture for backlog findings: Findings that are triaged to the backlog (out-of-scope for the current review or deferred by the team) should be preserved so they are not lost between review cycles. For each finding assigned to the backlog, run:

python3 scripts/deferred_capture.py \
  --title "<finding title>" \
  --source review \
  --context "Review dimension: <dimension>. <finding description>"

The <dimension> value should match the review skill that surfaced the finding (e.g. bug-review, api-review, architecture-review). This runs automatically after the action plan is finalised, without prompting the user.

Review Modes

Auto-Detect (default)

Automatically selects skills based on codebase analysis.

Focused Mode

Run specific review domains:

• /full-review api → api-review only
• /full-review architecture → architecture-review only
• /full-review bugs → bug-review only
• /full-review tests → test-review only

Full Review Mode

Run all applicable review skills:

• /full-review all → Execute all detected skills

Quality Gates

Each review must: 1. Establish proper context 2. Execute all selected skills successfully 3. Document findings with evidence 4. Prioritize recommendations by impact 5. Create action plan with owners

Deliverables

Executive Summary

• Overall codebase health assessment
• Critical issues requiring immediate attention
• Review frequency recommendations

Domain-Specific Reports

• API surface analysis and consistency
• Architecture alignment with ADRs
• Test coverage gaps and improvements
• Bug analysis and security findings
• Performance and maintainability recommendations

Integrated Action Plan

• Prioritized remediation tasks
• Cross-domain dependencies
• Assigned owners and target dates
• Follow-up review schedule

Modular Architecture

All review skills use a hub-and-spoke architecture with progressive loading:

• `pensive:shared`: Common workflow, output templates, quality checklists
• Each skill has `modules/`: Domain-specific details loaded on demand
• Cross-plugin deps: imbue:proof-of-work, imbue:diff-analysis/modules/risk-assessment-framework

This reduces token usage by 50-70% for focused reviews while maintaining full capabilities.

Exit Criteria

• All selected review skills executed
• Findings consolidated and prioritized
• Action plan created with ownership
• Evidence logged per structured output format

Supporting Modules

• Review workflow core - standard 5-step workflow pattern for all pensive reviews
• Output format templates - finding entry, severity, action item templates
• Quality checklist patterns - pre-review, analysis, evidence, deliverable checklists

Troubleshooting

Common Issues

If the auto-detection fails to identify the correct review skills, explicitly specify the mode (e.g., /full-review rust instead of just /full-review). If integration fails, check that TodoWrite logs are accessible and that evidence files were correctly written by the individual skills.

Output Format Templates

Standard templates for consistent review deliverables.

Top-Level Structure

# [Review Type] Review: [Subject]

## Executive Summary
[High-level overview, key findings count, overall assessment]

## Findings Summary
[Count by severity: Critical, High, Medium, Low]

## Detailed Findings
[Organized by category or severity]

## Action Items
[Prioritized recommendations with owner and next step]

## Evidence Appendix
[Supporting code snippets, references, measurements]

Finding Entry Template

### [Category]: [Short Title]

**Severity**: [Critical|High|Medium|Low]
**Location**: [File path:line numbers or component name]
**Category**: [Specific category from domain]

**Issue**:
[Clear description of what's wrong]

**Evidence**:
[Code snippet, measurement, or observation]

**Why This Matters**:
[The underlying principle or rule being violated.
Explain the concept, not just the symptom.]

**Proof**:
[Link to authoritative best-practice documentation.
Prefer: language docs, OWASP, PEPs, style guides,
RFCs. Summarize what the link teaches.]

**Teachable Moment**:
[How this lesson generalizes beyond this specific
finding. When else would this principle apply?]

**Recommendation**:
[Specific steps to resolve, with concrete next action]

**References**: [Evidence appendix section or external docs]

Educational Depth by Severity

Severity Definitions

Critical: Security vulnerability, data loss risk, system failure potential High: Significant functionality issues, major violations, substantial technical debt Medium: Moderate violations, code quality issues, maintainability concerns Low: Minor style issues, optimization opportunities, documentation gaps

Action Items Template

## Action Items

### Immediate (Critical/High Severity)
1. [Action] - [Rationale] - [Reference to finding]
2. ...

### Short-term (Medium Severity)
1. [Action] - [Rationale] - [Reference to finding]
2. ...

### Long-term (Low Severity / Improvements)
1. [Action] - [Rationale] - [Reference to finding]
2. ...

Evidence Appendix Template

## Evidence Appendix

### E1: [Short Reference Name]
**Related to**: Finding [X]
**File**: `/path/to/file.ext:lines`

[code snippet or measurement]

**Context**: [Why this evidence matters]

---

### E2: [Next Reference]
...

Summary Statistics Template

## Review Statistics

- **Total Items Reviewed**: [count]
- **Findings by Severity**:
  - Critical: [count]
  - High: [count]
  - Medium: [count]
  - Low: [count]
- **Categories Analyzed**: [list]
- **Recommendations**: [count]

Usage Notes

1. Adapt section headings to domain (e.g., "Endpoints" for API, "Components" for architecture) 2. Always link findings to evidence 3. Keep Executive Summary under 5 sentences 4. validate every finding has a concrete next step 5. Use consistent severity assessment across entire review

Quality Checklist Patterns

Standard quality assurance checklists for review deliverables.

Pre-Review Checklist

Execute before starting analysis:

• [ ] Scope clearly defined and documented
• [ ] Review criteria identified (use domain-specific patterns)
• [ ] Success criteria established
• [ ] Evidence logging strategy prepared
• [ ] Output template selected and customized

Analysis Quality Checklist

Execute during deep analysis phase:

• [ ] All scope items examined
• [ ] Domain-specific criteria applied consistently
• [ ] Severity assessed using standard definitions
• [ ] Patterns and anti-patterns identified
• [ ] Cross-references validated
• [ ] Edge cases considered

Evidence Quality Checklist

Execute during evidence capture:

• [ ] Every finding has supporting evidence
• [ ] File paths and line numbers included
• [ ] Code snippets are minimal and focused
• [ ] Context preserved for each evidence item
• [ ] Evidence appendix organized and referenced
• [ ] Reasoning chains documented

Deliverable Completeness Checklist

Execute before finalizing output:

• [ ] Executive summary present and concise
• [ ] All findings documented with required fields:
• [ ] Severity assigned
• [ ] Location specified
• [ ] Category identified
• [ ] Issue described
• [ ] Evidence provided
• [ ] Impact explained
• [ ] Recommendation actionable
• [ ] Action items prioritized by severity
• [ ] Evidence appendix complete
• [ ] Summary statistics included
• [ ] Output follows template structure

Recommendation Quality Checklist

Execute for each recommendation:

• [ ] Specific and actionable
• [ ] Addresses root cause, not just symptoms
• [ ] Feasible within project constraints
• [ ] Prioritized appropriately
• [ ] Linked to finding
• [ ] Includes rationale

Review Consistency Checklist

Execute before final delivery:

• [ ] Severity levels applied consistently
• [ ] Terminology used consistently
• [ ] Categories align with domain standards
• [ ] Similar issues grouped appropriately
• [ ] No contradictory recommendations
• [ ] Style and tone professional throughout

Exit Criteria Validation

Final check before completion:

• [ ] All TodoWrite items marked complete
• [ ] Workflow steps executed in sequence
• [ ] Quality checklists satisfied
• [ ] Output validated against template
• [ ] Evidence complete and linked
• [ ] Deliverable ready for stakeholder review

Usage Pattern

Integrate into Step 5 (Deliverable Assembly) of review workflow:

# Before marking final todo as complete
print("Validating deliverable quality...")
# Run through Deliverable Completeness Checklist
# Run through Review Consistency Checklist
# Run through Exit Criteria Validation
# Only then mark todo complete

Customization

Domain-specific reviews may extend these checklists with:

• Additional domain criteria (e.g., security-specific checks)
• Tool-specific validation (e.g., linter results)
• Compliance requirements (e.g., regulatory standards)

Extend, don't replace, these baseline checklists.

Review Workflow Core

Standard 5-step workflow pattern for all pensive review skills.

Workflow Structure

Step 1: Context Establishment

TodoWrite Item: "Establishing review context"

Actions: 1. Identify review scope and boundaries 2. Gather relevant files and documentation 3. Establish success criteria 4. Load domain-specific patterns (if applicable)

Output: Context summary with scope definition

Step 2: Scope Inventory

TodoWrite Item: "Creating scope inventory"

Actions: 1. Catalog all items to review (files, components, endpoints, etc.) 2. Categorize by type, complexity, or domain area 3. Prioritize based on risk, complexity, or impact 4. Create initial structure for findings

Output: Structured inventory with categories

Step 3: Deep Analysis

TodoWrite Item: "Performing deep analysis"

Actions: 1. Apply domain-specific review criteria 2. Identify patterns, anti-patterns, violations 3. Assess severity (Critical, High, Medium, Low) 4. Cross-reference with best practices 5. Capture evidence for each finding

Output: Detailed findings with evidence

Step 4: Evidence Capture

TodoWrite Item: "Capturing evidence"

Integration with imbue:proof-of-work: 1. Document code snippets with file paths and line numbers 2. Record reasoning chains for conclusions 3. Link findings to specific violations or patterns 4. Preserve context for future reference

Output: Evidence appendix linked to findings

Step 5: Deliverable Assembly

TodoWrite Item: "Assembling final deliverable"

Actions: 1. Structure findings by severity and category 2. Format recommendations with actionable steps 3. Create prioritized action items 4. Validate completeness against exit criteria 5. Generate final output using templates

Output: Complete review deliverable

TodoWrite Integration

Create tasks at workflow start:

TodoWrite({
    "todos": [
        {"content": "Establish review context", "status": "pending", "activeForm": "Establishing review context"},
        {"content": "Create scope inventory", "status": "pending", "activeForm": "Creating scope inventory"},
        {"content": "Perform deep analysis", "status": "pending", "activeForm": "Performing deep analysis"},
        {"content": "Capture evidence", "status": "pending", "activeForm": "Capturing evidence"},
        {"content": "Assemble final deliverable", "status": "pending", "activeForm": "Assembling final deliverable"}
    ]
})

Mark each as in_progress when starting, completed when finished.

Exit Criteria

Before marking workflow complete:

• [ ] All scope items analyzed
• [ ] Evidence captured for each finding
• [ ] Recommendations are actionable
• [ ] Output follows format templates
• [ ] Quality checklist satisfied