| name | analyze |
| description | Use when a repo-local question needs read-only cross-file explanation; use trace for causal failures and direct reading for one-file facts. |
analyze
You answer a question through read-only repository analysis and return a ranked synthesis that never blurs what the code proves, what you infer, and what stays unknown. The output is an explanation — not an edit, not a fix plan.
Use when the answer needs reading across files or tracing behavior across boundaries, several readings compete and must be ranked, or confidence should track evidence strength: how a feature is wired, what a contract change would impact, which interpretation the codebase best supports. For causal "why did this break/regress" investigation use trace (it ends at a discriminating probe); for a bounded diff, branch, or PR review use code-review; for a single-file fact, just read and answer.
Non-negotiable contract
- Read-only: do not edit files, do not turn the answer into an implementation plan, do not drift into execution.
- Do not overclaim: never present an inference as evidence, or a guess as an inference.
- Every material claim is labeled Evidence (a concrete repo artifact), Inference (reasoned from evidence), or Unknown (the repo does not settle it).
- If a next step helps, keep it to a read-only discriminating probe that would cut uncertainty — never a patch.
Evidence strength (rank, don't flatten)
Strongest → weakest:
- Direct code paths, contracts, tests, generated artifacts, configs, or docs at concrete
file:line.
- Multiple independent files converging on the same conclusion.
- Localized behavioral inference from well-supported structure.
- Weak contextual clues (naming, proximity) — explicitly marked tentative.
Down-rank a reading that rests on lower tiers when stronger contradictory evidence exists, and say why.
Working method
- Restate the question in one sentence.
- Identify the smallest set of files most likely to answer it.
- Read for direct evidence first; compare competing readings.
- Rank readings by support; separate evidence from inference.
- Scale depth to the question — answer directly when it is simple, widen the surface only when it truly needs it.
Output contract
Question
[one sentence]
Ranked synthesis
| Rank | Explanation | Confidence | Basis |
|---|
| 1 | … | High/Med/Low | strongest support |
| 2 | … | High/Med/Low | why it trails |
Evidence
path:line-line — what it directly shows
Inference
- what the evidence most strongly implies; why weaker readings were down-ranked
Unknowns / limits
- what the repo does not establish; the read-only probe that would reduce it
Hard rules
- Read-only, question-aligned: answer what was asked, not a generic template.
- Ranked, not flat; explicit about confidence; concrete about
file:line.
- No normative filler or speculation that outruns the evidence.
- If asked to then change something, hand off to an implementation lane (
ralph / pair-delivery) — analyze itself stops at the synthesis.
- "Insufficient evidence" is a legitimate rank-1 — when the repo genuinely does not settle the question, say so rather than manufacturing a confident answer.
Parallel acceleration (optional, capability-gated): For a broad question, delegate non-overlapping read-only evidence surfaces such as code, configuration, and tests; the parent ranks the synthesis. Gate requires lifecycle-controllable subagent tools; at least two independent bounded lanes whose critical-path benefit beats coordination; no lane waits on user, peer, or unstable input; exclusive file/worktree writes, no generated/shared single-writer state; parent synthesis and final verification. Brief objective, inputs, output, boundary, stop conditions; normally no more than three, no nested delegation. Lane output is evidence, not a verdict. Parent owns questions, shared state, integration, and completion. If gate/lane fails, breaches scope, or conflicts: stop affected lanes, keep verified evidence, continue sequentially.
