---
name: analyze
description: Run read-only deep repository analysis with ranked synthesis, concrete evidence, and explicit Evidence/Inference/Unknown boundaries.
argument-hint: "<question>"
---

# /omagy:analyze

Use this skill when the user wants a grounded repository explanation before
code changes: "analyze", "investigate", "why does", "what is causing", "how is
this wired", or "what would be impacted".

This is the Omagy adaptation of OMX analyze. It is read-only by contract and
uses agy-native read-only inspection or bounded `omagy explore` probes instead
of Codex-specific runtime APIs.

## Command

Create the analysis contract and an initial safe probe:

```bash
omagy analyze --prompt "<question>" --json
omagy analyze --prompt "<question>" --probe "<narrow repo lookup>" --json
```

The command returns:

- the question
- `read_only: true`
- the required output sections
- the `Evidence`, `Inference`, and `Unknown` labels
- recommended agy lanes: `explorer` and `analyst`
- an initial `omagy explore` probe result when a safe local route matches

## Non-Negotiable Contract

- Do not edit files.
- Do not run formatters, test suites, builds, package installs, or mutating
  commands from analyze.
- Do not silently switch into implementation.
- Do not turn the answer into a fix plan as the primary output.
- Do not overclaim certainty.
- Do not invent facts that are not supported by repository evidence.

If a next step is useful, keep it to a discriminating read-only probe that would
reduce uncertainty.

## Question-Aligned Synthesis

Answer the user's actual question first.

- Start from the asked question, not a generic debugger template.
- Keep the synthesis scoped to what the user needs to know.
- Scale the depth to the request: for simple or obvious questions, reduce
  exploration intensity and answer directly after enough reading.
- For broader questions, expand the search surface but keep the final answer
  tightly synthesized.
- Do not let implementation ideas, cleanup suggestions, or broad planning
  overtake the explanation unless the user explicitly asks for next steps.

## Evidence Rules

Every material claim must be labeled as one of:

1. **Evidence** - directly supported by concrete files, tests, docs, configs,
   command output, or artifacts.
2. **Inference** - a reasoned conclusion drawn from the evidence.
3. **Unknown** - a question current repository evidence does not settle.

Never present an inference as direct evidence. Never present a guess as an
inference.

### Acceptable Evidence

Prefer stronger evidence over weaker evidence:

1. Direct code paths, contracts, tests, generated artifacts, configs, or docs
   with concrete file references.
2. Multiple independent files pointing to the same conclusion.
3. Localized behavioral inference from well-supported code structure.
4. Weaker contextual clues that remain explicitly marked as tentative.

Unsupported speculation is not evidence.

## Working Method

1. Restate the question.
2. Run `omagy analyze --prompt "<question>" --json` or include a narrower
   `--probe` when the first file/text lookup is obvious.
3. Read the returned contract and initial probe evidence.
4. Use agy's native `explorer` or `analyst` subagent only for bounded read-only
   sub-questions when parallel exploration helps.
5. Compare competing explanations.
6. Rank explanations by support.
7. Answer with explicit evidence-vs-inference boundaries.

## Parallel Exploration And Team Escalation

Default to direct read-only analysis for simple questions.

When parallelism helps, prefer bounded in-session or agy-native exploration
first:

- Use `explorer` for specific code path, file, symbol, or config questions.
- Use `analyst` for a bounded subsystem explanation or evidence synthesis.
- Keep each lane scoped to a concrete read-only sub-question.

Use `/omagy:team` only when the analysis needs durable coordination, shared task
state, mailbox/dispatch flow, worktrees, explicit lifecycle control, or
long-running parallel investigation that should survive beyond one local
reasoning burst.

Team escalation rules:

- Do not present `/omagy:team` as the default analyze path.
- Do not replace `/omagy:team` with ad-hoc prompt fanout when durable team
  runtime is required.
- If `/omagy:team` is used, follow the Omagy team runtime lifecycle: context
  intake, startup evidence, state-backed monitoring, terminal task evidence, and
  shutdown evidence.
- If team runtime is unavailable or inappropriate for the current agy session,
  stay on direct read-only inspection plus bounded `explorer` / `analyst` lanes
  and state the limitation.

## Output Contract

```text
Question
<brief restatement>

Ranked synthesis
| Rank | Explanation | Confidence | Basis |
|------|-------------|------------|-------|
| 1 | ... | High/Medium/Low | ... |

Evidence
- path/to/file:line - direct evidence

Inference
- conclusion drawn from evidence

Unknowns / limits
- what repository evidence does not establish
```