analyze

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:

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

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