analyze

# Analyze — Evidence-Driven Investigation

Use this skill for ambiguous, causal, evidence-heavy questions where the goal is to explain **why** an observed result happened, not to jump directly into fixing or rewriting code.

## Good entry cases

Use `$analyze` when the problem is:

- ambiguous or causal
- evidence-heavy
- best answered by exploring competing explanations
- requires reading multiple files and reasoning across them

Examples:
- runtime bugs and regressions
- performance / latency / resource behavior
- architecture / premortem / postmortem analysis
- config / routing / orchestration behavior explanation
- dependency analysis or impact assessment
- "given this output, trace back the likely causes"

## Do not use when

- User wants code changes made — use `$ralph` or executor instead
- User wants a full plan with acceptance criteria — use `$plan` instead
- User wants a quick file lookup — use explore agent instead
- User asks a simple factual question answerable from one file — just read and answer

## Core investigation contract

Always preserve these distinctions:

1. **Observation** — what was actually observed
2. **Hypotheses** — competing explanations
3. **Evidence For** — what supports each explanation
4. **Evidence Against / Gaps** — what contradicts it or is still missing
5. **Current Best Explanation** — the leading explanation right now
6. **Critical Unknown** — the missing fact keeping the top explanations apart
7. **Discriminating Probe** — the highest-value next step to collapse uncertainty

Do **not** collapse into:
- a generic fix-it coding loop
- a generic debugger summary
- a raw dump of output
- fake certainty when evidence is incomplete

## Evidence strength hierarchy

Treat evidence as ranked, not flat. From strongest to weakest:

1. **Controlled reproductions / direct experiments / uniquely discriminating artifacts**
2. **Primary source artifacts with tight provenance** (trace events, logs, metrics, configs, git history, file:line behavior)
3. **Multiple independent sources converging on the same explanation**
4. **Single-source code-path or behavioral inference**
5. **Weak circumstantial clues** (timing, naming, stack order, resemblance to prior bugs)
6. **Intuition / analogy / speculation**

Explicitly down-rank hypotheses that depend mostly on lower tiers when stronger contradictory evidence exists.

## Strong falsification rules

Every serious investigation must try to falsify its own favorite explanation.

For each top hypothesis:
- collect evidence **for** it
- collect evidence **against** it
- state what distinctive prediction it makes
- state what observation would be hard to reconcile with it
- identify the cheapest probe that would discriminate it from the next-best alternative

Down-rank a hypothesis when:
- direct evidence contradicts it
- it survives only by adding new unverified assumptions
- it makes no distinctive prediction compared with rivals
- a stronger alternative explains the same facts with fewer assumptions

## Team-mode orchestration (when using $team)

For complex investigations, use `$team` to run parallel tracer lanes:

1. Restate the observed result or "why" question precisely
2. Generate multiple deliberately different candidate hypotheses
3. Spawn **3 tracer lanes** via `$team`
4. Assign one lane per hypothesis
5. Each lane gathers evidence **for** and **against** its hypothesis
6. Run a **rebuttal round** between the leading hypothesis and the strongest alternative
7. Merge findings into a ranked synthesis

### Default hypothesis lanes

Unless the problem strongly suggests a better partition:

1. **Code-path / implementation cause**
2. **Config / environment / orchestration cause**
3. **Measurement / artifact / assumption mismatch cause**

### Worker contract

Each worker must:
- own exactly one hypothesis lane
- gather evidence **for** and **against** the lane
- rank evidence strength
- call out missing evidence and failed predictions
- name the **critical unknown** for the lane
- recommend the best **discriminating probe**
- avoid collapsing into implementation

### Cross-check lenses

After the initial evidence pass, pressure-test with these lenses when relevant:

- **Systems lens** — queues, retries, backpressure, feedback loops, upstream/downstream dependencies
- **Premortem lens** — assume the current best explanation is wrong; what failure mode would embarrass the trace later?
- **Science lens** — controls, confounders, measurement bias, falsifiable predictions

## Execution policy

- Default to concise, evidence-dense progress and completion reporting unless the user or risk level requires more detail
- Treat newer user task updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints
- If correctness depends on additional inspection, retrieval, execution, or verification, keep using the relevant tools until the analysis is grounded
- Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, or preference-dependent

**Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.

**Good:** The user changes only the output shape or downstream delivery step. Preserve earlier non-conflicting workflow constraints and apply the update locally.

## Execution steps

1. **Identify the analysis type**: Architecture, bug investigation, performance, or dependency analysis
2. **Gather relevant context**: Read or identify the key files involved
3. **Generate hypotheses**: At least 2-3 competing explanations
4. **Route to analyzer**:
   - For simple cases: investigate directly with file reads and reasoning
   - For complex cases: use `$team` with tracer lanes
   - Use `ask_codex` with `agent_role: "architect"` when available
5. **Falsify**: Try to break your own best hypothesis
6. **Return structured findings**: Present with evidence, file references, and actionable recommendations

## Output format

### Observed Result
[What happened]

### Ranked Hypotheses
| Rank | Hypothesis | Confidence | Evidence Strength | Why it leads |
|------|------------|------------|-------------------|--------------|
| 1 | ... | High / Medium / Low | Strong / Moderate / Weak | ... |

### Evidence Summary by Hypothesis
- Hypothesis 1: ...
- Hypothesis 2: ...

### Evidence Against / Missing Evidence
- Hypothesis 1: ...
- Hypothesis 2: ...

### Most Likely Explanation
[Current best explanation with file:line references]

### Critical Unknown
[Single missing fact keeping uncertainty open]

### Recommended Next Step
[Single best action — either a discriminating probe or a fix recommendation]

## Quality bar

Good analysis output is:
- evidence-backed with file:line references
- concise but rigorous
- skeptical of premature certainty
- explicit about missing evidence
- practical about the next action
- explicit about why weaker explanations were down-ranked

Task: {{ARGUMENTS}}