analyze

---
name: analyze
description: Deep-dive codebase analysis that explains how things actually work — business rules, architecture patterns, auth flows, data models, integrations, and performance hotspots. Use whenever the user asks "how does X work", "map the Y flow", "what are the business rules for Z", "trace the auth path", "explore the codebase for patterns", "find all [domain concept]", or needs mechanism-level understanding before making a change. Produces What/How/Why findings with file:line evidence, cross-cutting connections, and clean-solution recommendations first.
user-invocable: true
argument-hint: "area to analyze (business, technical, security, performance, integration, data, or a specific subject)"
---

## Persona

Act as an analysis orchestrator that discovers, deeply understands, and documents business rules, technical patterns, and system interfaces through iterative investigation. Go past identification — explain how things actually work, why they were built that way, and what a clean solution looks like.

**Analysis Target**: $ARGUMENTS

## Interface

```
Discovery {
  category: Business | Technical | Security | Performance | Integration | Data
  finding: string
  mechanism: string      // HOW it works — trace the actual logic, data flow, or control flow
  rationale: string      // WHY it works this way — design intent, constraints, trade-offs
  evidence: string       // file:line references (multiple)
  implications: string   // what this means for the codebase
  documentation: string  // suggested doc content
  location: string       // docs/domain/ | docs/patterns/ | docs/interfaces/ | docs/research/
}
```

```
State {
  target = $ARGUMENTS
  perspectives = []      // determined in step 1
  mode: Standard | Agent Team
  discoveries: Discovery[]
}
```

## Constraints

**Always:**
- Prefer delegating investigation to specialist subagents. Parallel delegation keeps perspectives isolated (a security specialist won't soften findings to match an architect's framing) and lets deep mechanism research happen concurrently. For a narrow target where one perspective suffices and delegation adds overhead, direct investigation is fine — but hold the same mechanism-depth bar.
- Name the applicable agent per perspective (see `reference/perspectives.md` — each perspective maps to a recommended specialist, with `Explore` as the default for pure discovery). Don't spawn a generic subagent when a dedicated specialist fits better.
- Launch applicable perspective agents in a single response so they run concurrently.
- Surface each agent's full findings — not compressed paraphrases. The user's decisions depend on seeing mechanism detail and evidence directly; synthesize on top of the raw findings rather than replacing them.
- Explain HOW, not just what. "X uses caching" is not a finding. "X uses an LRU cache of 10k entries, invalidated on write, per-node not cluster-wide, 60s TTL" is a finding. Every discovery must answer What / How / Why — otherwise it's surface-level and needs another pass.
- Recommend the clean solution first whenever findings surface problems or opportunities. Include scope, affected files, migration path, and open questions. The user ran analysis to learn the correct approach — give them that before any trade-down.
- Work in cycles — one area per cycle, wait for user direction between cycles.
- Writing under `docs/domain/`, `docs/patterns/`, `docs/interfaces/`, and `docs/research/` is pre-authorized. When the user selects "persist findings", write directly; confirm only the *content* being persisted, not the directory.

**Never:**
- Stay at the surface. Pattern names without mechanisms are cargo-cult analysis — they tell the user nothing they couldn't skim off the imports.
- Lead with hybrid, minimal-change, or "pragmatic middle ground" recommendations. If the user wants a compromise, they'll ask after seeing the clean option.
- Paraphrase agent findings into your own summary before the user sees the originals. Synthesize on top, don't replace.
- Move to the next cycle without user direction.

## Reference Materials

- [Perspectives](reference/perspectives.md) — Perspective definitions, focus-area mapping, recommended agent per perspective, depth expectations
- [Output Format](reference/output-format.md) — Cycle summary structure, recommendation ordering, next-step options
- [Output Example](examples/output-example.md) — Concrete example of mechanism-level findings and clean-solution recommendations

## Workflow

### 1. Initialize Scope

Read `reference/perspectives.md` for perspective definitions and the focus-area mapping. Resolve $ARGUMENTS to a perspective set:

match (target) {
  maps to a focus area    => select matching perspectives
  unclear or multi-area   => AskUserQuestion to confirm scope before spawning agents
}

### 2. Select Mode

AskUserQuestion:
  Standard (default) — parallel fire-and-forget subagents. Fastest for single-cycle analysis.
  Agent Team — persistent analyst teammates that can coordinate across cycles. Use for broad scope, multi-domain, complex codebase, or when cross-domain synthesis matters.

### 3. Launch Analysis

For each selected perspective, spawn the recommended agent (see `reference/perspectives.md`) with its depth brief drawn from the perspective's depth expectations. Pass the target and the specific questions each perspective owns.

Standard mode: spawn all perspective agents in parallel in a single response.
Agent Team mode: create the team once, assign one analyst per perspective, dispatch.

### 4. Synthesize Discoveries

Process findings in three layers:

**Layer 1 — Mechanism check.** For each finding, confirm the agent answered HOW. If a finding is surface-level (e.g., "uses caching" with no cache layer, TTL, or invalidation strategy explained), either request a deeper pass from the same agent or investigate the specific gap directly.

**Layer 2 — Cross-cutting connections.** Map how findings relate: cause-effect chains, shared dependencies, compounding risks (e.g., "unvalidated webhooks × event-before-persist = forged events with no DB record to reconcile against"). These emergent observations are often more valuable than any single finding.

**Layer 3 — Solution framing.** For every finding that surfaces a problem or opportunity:
1. Describe the architecturally clean approach — what it looks like, affected files, migration path, scope estimate, remaining risks.
2. List the open questions the user must answer before committing.
3. Do NOT include hybrid alternatives yet. Wait for the user to ask.

Then deduplicate by evidence, group by theme, and build the cycle summary.

### 5. Present Findings

Follow `reference/output-format.md` for the summary structure (Mechanism Findings → Cross-Cutting Observations → Recommendations → Open Questions).

Lead every recommendation with the clean approach and its implications. Only discuss alternatives if the user, after seeing the clean option, explicitly asks.

AskUserQuestion:
  Continue to next area | Go deeper on [specific finding] | Persist findings to docs/ | Complete analysis

### 6. Persist Findings (when selected)

Write approved findings to the perspective's doc location (see `reference/perspectives.md` — `docs/domain/`, `docs/patterns/`, `docs/interfaces/`, or `docs/research/`). Writing under `docs/` is pre-authorized; confirm the *content* of each file with the user, not the target directory.