spm1001/titans

/titans — Code Review Triad

Three reviewers, three lenses. Dispatch in parallel, synthesize findings.

When to Use

• After substantial work — Before /close, when a feature/fix/refactor is "done"
• Before shipping — Final quality gate
• Periodic hygiene — "What's rotting that I haven't noticed?"

When NOT to Use

• Quick fixes under 50 lines
• Exploratory spikes
• Throwaway scripts (unless they stopped being throwaway)
• When you need speed over thoroughness

Beyond Code Review

The three-lens pattern works for more than code. The underlying structure (hindsight/craft/foresight) applies to any artifact worth reviewing thoroughly:

| Domain | Epimetheus asks | Metis asks | Prometheus asks | |--------|-----------------|------------|-----------------| | Documentation | What's stale or misleading? | Is it clear and well-structured? | Does it serve future readers? | | Architecture | What's fragile or debt-laden? | Does it follow good patterns? | Does it enable what we're building toward? | | Process | What's broken or painful? | Is it efficient and clear? | Will it scale with the team? | | CLAUDE.md | What's wrong or outdated? | Is it well-organized? | What should future Claude know? |

Discovered Jan 2026: Used titans pattern to review trousse itself for CLAUDE.md updates. The three lenses surfaced different categories of findings — infrastructure bugs (Epimetheus), stale references (Metis), undocumented contracts (Prometheus) — that a single-pass review would have missed.

When adapting: Adjust the reviewer briefs for the domain. The output structure (findings, assumptions, could-not-assess, questions) remains useful regardless of what you're reviewing.

The Triad

| Titan | Lens | Question | Focus | |-------|------|----------|-------| | Epimetheus | Hindsight | "What has already gone wrong, or will bite us?" | Bugs, debt, fragility, security | | Metis | Craft | "Is this well-made, right now, for what it is?" | Clarity, idiom, structure, tests | | Prometheus | Foresight | "Does this serve what we're building toward?" | Vision, extensibility, knowledge capture |

Why these three? Hindsight catches what's broken. Craft ensures current quality. Foresight protects future-you. Small overlaps are fine — they're perspectives, not partitions.

Orchestration

1. Scope the review

Before dispatching, establish:

• What to review — specific files, directory, or "everything touched this session"
• Context available — CLAUDE.md, README, architecture docs
• Goals if known — roadmap items, intended consumers, lifespan

If scope is unclear, ask. Don't review the entire codebase by accident.

2. Dispatch reviewers

Launch three parallel Task calls. Use Explore subagent with model: "opus" — deep review needs Opus-level reasoning, not Haiku speed.

Each reviewer receives:

• The Reviewer Brief for their lens (from references/REVIEWERS.md)
• The scoped files/context
• Awareness of the other two reviewers (to minimize redundancy)
• The output structure template

Task(
  subagent_type: "Explore",
  model: "opus",
  description: "EPIMETHEUS review of [scope]",
  prompt: "[Reviewer brief from REVIEWERS.md] + [scoped files] + [output template]"
)

Dispatch all three in a single message (parallel execution).

3. Collect outputs

Each reviewer returns structured findings. See Output Structure below.

Partial failures: If a reviewer times out, errors, or returns malformed output:

• Proceed with available outputs (two reviews > none)
• Note the gap in synthesis ("Epimetheus did not complete — hindsight lens missing")
• Consider re-running the failed reviewer with tighter scope

4. Synthesize

Merge outputs into actionable summary:

• High-priority findings (multiple reviewers agree)
• Conflicts reveal trade-offs (disagreements worth surfacing)
• "Could not assess" → documentation debt
• Critical path before shipping

See references/SYNTHESIS.md for synthesis patterns.

---

Output Structure (All Reviewers)

Each reviewer uses this template:

## [TITAN] Review

### Findings
Numbered list of issues, each with:
- What: the problem
- Where: file/line/function
- Severity: critical | warning | note
- Fix complexity: trivial | moderate | significant

### Assessed Under Assumptions
State the assumption, then the conditional finding:
- "Assuming this is a long-lived component: [concern]"
- "If throwaway prototype, this concern evaporates"

### Could Not Assess
What's missing that blocks review:
- "No visibility into intended consumers"
- "Can't evaluate against patterns — no access to rest of codebase"
- "Token refresh flow undocumented"

### Questions That Would Sharpen This Review
Specific, answerable questions:
- "Is this called by other agents or only orchestration?"
- "What's the expected lifespan?"
- "Who are the intended consumers?"

"Could not assess" is itself diagnostic. A codebase that leaves Prometheus constantly asking "what are we building toward?" has a documentation problem worth surfacing.

---

Synthesis Output

After collecting all three reviews, produce:

## Review Triad Synthesis

### High-Priority Findings (Multiple Reviewers)
| Finding | E | M | P | Action |
|---------|---|---|---|--------|
| [issue] | ✓ | ✓ | — | [fix]  |

### Conflicts Reveal Trade-offs
| Trade-off | Metis says | Prometheus says | Resolution |
|-----------|------------|-----------------|------------|
| [tension] | [position]| [position]      | [decision] |

### "Could Not Assess" → Documentation Debt
Repeated across reviewers:
- [gap] — [what's needed]

### Critical Path Before Shipping
| # | Issue | Risk | Fix Complexity |
|---|-------|------|----------------|

### Lower Priority (Track as Tech Debt)
- [items to track but not block on]

### Questions to Resolve
1. [question surfaced by review]

---

Reference Files

| Reference | When to Read | |-----------|--------------| | REVIEWERS.md | Detailed briefs for each Titan | | SYNTHESIS.md | Patterns for merging outputs, handling conflicts |

---

Observed Token Consumption

From test runs, reviewers tend to use tokens in this order:

• Epimetheus uses the most — deepest spelunking through code paths
• Metis uses moderate — structural analysis, less exploration
• Prometheus uses the least — architectural assessment from less code

This varies by codebase size and scope clarity. If a reviewer seems to be looping, it usually indicates unclear scope — consider interrupting and re-scoping rather than waiting it out.

Anti-Patterns

| Pattern | Problem | Fix | |---------|---------|-----| | Vague scope | Reviewers loop, miss focus | Explicit file list or "changes since X" | | Skip synthesis | Three reports, no action | Always synthesize findings | | Ignore partial failures | Miss perspectives | Report which reviewer failed, proceed with others | | Review before work is "done" | Premature review | Complete the feature first |

---

Integration with /open and /close

/open
  ↓
[substantial work]
  ↓
/titans  ← you are here
  ↓
[address critical findings]
  ↓
/close

/titans findings can feed into /close:

• Critical issues → "Now" bucket (fix before closing)
• Lower priority → "Next" bucket (create tracker items)
• Documentation debt → handoff Gotchas section