git:20260930.0395bf2 to git:20261010.8cfe65f

48 added, 107 removed. Audit A to A.

---

name: analyze

- description: Deep-research analysis of a codebase or question. Plans an analysis (purpose + a goals rubric), gets your approval, then runs a dynamic-workflow that fans out cited research, validates it against the goals rubric in a loop, and synthesizes one cited report. Use for "how does X work", "map the Y flow", "research Z", or any mechanism-level investigation that must be evidence-backed and review-worthy.

+ description: Deep-research analysis of a codebase, a topic, or both. Clarifies the question, agrees the research angles with you, then runs a dynamic workflow that gathers cited claims per angle, merges duplicates, has independent skeptics try to refute every claim, and writes one cited report from the claims that survived. Use for "how does X work", "map the Y flow", "research Z", or any mechanism-level question that must be evidence-backed.

user-invocable: true

argument-hint: "what to analyze (e.g. 'how does the auth flow work')"

---

## Persona

- Act as the analysis orchestrator. You turn a request into an **analysis plan** (a terse purpose

- and a `goals` rubric), get the user to approve or refine it, then install and launch the reusable

- analysis workflow. You do **not** perform the research or write the report yourself — the workflow

- holds the research→validate loop and the synthesis. Your job is the setup around it: frame the

- plan, seed the research tasks, launch, and report what came back.

+ Act as the analysis orchestrator. You turn a request into a precise research question and a set of

+ research angles, get the user to confirm them, then author and run **one dynamic workflow** (the

+ Workflow tool with an inline script you write) that does the research, verification, and synthesis.

+ You do **not** research or write findings yourself — nothing reaches the report unless a verifier

+ opened its source.

**Analysis Target**: $ARGUMENTS

## Constraints

**Always:**

- - Show the plan in the chat before asking for approval — render the purpose, goals, and topics inline

- as readable text; never gate approval on a file path alone.

- - Lead every decision menu with the mechanism explanation and a single recommended option, written as

- chat text first — a menu confirms a recommendation; it does not stand in for the analysis. This

- applies to every gate in this skill (approve/refine, upgrade, finalize), not just plan approval.

- - Get explicit user approval of the plan (purpose + goals) before launching. The `goals` are the

- rubric the workflow validates against, so they must be right first.

- - Keep the information split clean: the skill authors the plan and seeds tasks; the workflow's

- agents do the research, validation, and synthesis via the tracker.

- - Seed research tasks and pass `taskScript` + `home` so the workflow's agents use `task.js` as the

- researcher↔validator channel.

- - Require citations: every claim in the final report must trace to a source (code `file:line` or a

- URL). The workflow's grade pass enforces this (among other quality dimensions) and revises the report

- until it clears; surface the grade.

- - Writing under `.start/analysis/` and `docs/research/` is pre-authorized.

+ - Clarify before launching: every angle, claim, and verification in the run derives from the question.

+ - Show the question and the angles in the chat and get the user's confirmation before launching.

+ - Require citations: every claim carries a `file:line` or URL and a verbatim excerpt.

+ - Present refuted, unverified, and unanswered parts of the question as plainly as the findings.

+ - Writing under `docs/research/` is pre-authorized.

**Never:**

- - Do the research or write the report yourself — the workflow owns them. Concretely, once the plan is

- approved this orchestrator thread runs **no WebSearch/WebFetch** and does **no authoring or editing of

- the report or research findings**; those tools belong to the workflow's agents. (Copying the finished

- report to `docs/research/` in step 6 is a file copy, not authoring — that is still fine.)

- - Launch before the goals rubric is approved.

- - Present a bare decision menu with no analysis shown first, or offer a hybrid / "Both" option you would

- not yourself recommend — recommend one clean option and name its tradeoff instead of enumerating a

- compromise you have already flagged as wrong.

- - Overwrite a project's edited `.claude/workflows/analyze.js` without asking (see version check).

+ - Research, verify, or write findings outside the workflow, or add knowledge the workflow did not verify.

+ - Launch on a question the user has not confirmed.

## Reference Materials

- - [analyze.js](reference/analyze.js) — the golden, reusable workflow script (research → validate loop → synthesize → cite-check). Read its input-contract comment; it defines the `args` you build.

- - [template.md](template.md) — the analysis plan document.

+ - [Workflow Contract](reference/workflow.md) — stages, agent return schemas, counting rules, and result shape

+ - [Research Agent](reference/research-agent.md) — prompt for one research angle

+ - [Consolidate Agent](reference/consolidate-agent.md) — prompt for merging duplicate claims

+ - [Verify Agent](reference/verify-agent.md) — prompt for one adversarial voter

+ - [Synthesize Agent](reference/synthesize-agent.md) — prompt for the report

## Workflow

- ### 1. Frame the Plan and Scaffold

- Derive from `$ARGUMENTS`:

- - a slug `name` (kebab-case) and the next `[NNN]` by scanning `.start/analysis/`;

- - a terse `description` (the purpose);

- - a first draft of `goals` — 2–5 achievable, checkable objectives that would make the analysis

- worth a human's review (each phrased so the validator can rule it met/unmet by evidence);

- - a first draft of **3–6 research `topics`** — each an **independent angle** that can be investigated

- in parallel (e.g. split by subsystem, by data-flow, by external source, or by question), so the

- workflow fans out real concurrent research streams rather than one monolithic pass. If the subject

- genuinely warrants only one angle, say so explicitly rather than padding.

- Create `.start/analysis/[NNN]-[name]/` and write `analysis.md` from `template.md` with

- `status: draft`. Create the `.tracker/` directory.

- ### 2. Approve or Refine (interactive gate)

- **Display the full plan inline in the chat** — do not just write `analysis.md` and point at its path.

- Render, as chat text the user reads directly:

- - the **purpose** (description),

- - the **goals rubric** as a numbered list (these are exactly what the workflow validates against),

- - the **proposed research topics** — presented as the independent parallel research streams the

- workflow will fan out (so the user sees and can adjust the concurrency before launch).

- Then ask the user to choose:

- Approve — proceed with these goals

- Refine — adjust goals/topics/scope

- On refine, edit the `analysis.md` frontmatter, then **re-display the updated plan in the chat** and ask

- again. Loop until approved, then set `status: approved`. Do not proceed without approval — the goals

- are the rubric.

- ### 3. Seed the Tracker

- For each approved topic, create a research task (record the ids into `topicIds`):

- `node task.js create --home .start/analysis/[NNN]-[name] --type research --name "{topic}"`

- Optionally create one `--type goal` task per goal for visible rollup. Use the specify-meta skill's

- `task.js` (co-located with spec.py), run via the shell.

- ### 4. Install / Version-Check the Workflow

- The golden copy is this skill's `reference/analyze.js`; its first line is `// analyze-workflow: vN`.

+ ### 1. Clarify

- ```

- installed = <project>/.claude/workflows/analyze.js

- match:

- installed absent => create .claude/workflows/ if needed; copy bundled → installed; tell the user "installed analyze workflow v{N}".

- same version marker => proceed.

- bundled version > installed => ask under header "Upgrade": "Upgrade analyze workflow v{old} → v{new}?" — Upgrade (Recommended) | Keep current.

- installed version > bundled => project copy is ahead/hand-edited; keep it and note this.

- ```

+ If `$ARGUMENTS` is underspecified — no subsystem named, no scope, or ambiguous between several things

+ (e.g. "how does auth work" in a repo with session, API-key, and OAuth paths) — ask 2–3 clarifying

+ questions and keep asking until the user confirms the scope. Settle whether the answer comes from the

+ codebase, the web, or both. Weave the answers into one refined question.

- Never overwrite the installed file except on an explicit Upgrade choice or a first install.

+ ### 2. Scope the Angles

- ### 5. Launch the Workflow

+ Decompose the question into 2–6 angles that together cover it and can be researched concurrently by

+ agents with no shared context. Split along the axis the question actually has — subsystem, data-flow

+ stage, layer, external source, or sub-question. Angles must not overlap; do not pad a question that

+ genuinely has two. Give each a 2–4 word label and a concrete focus.

- Build `WorkflowArgs`: `name`, `home` (absolute), `taskScript` (absolute path to `task.js`),

- `description`, `goals`, `topics` (from step 3), `reportPath` = `home/report.md`, `maxRounds` (default 3).

- Set `status: in-progress`. Launch:

+ Present the refined question and the angles. Ask the user to *Launch*, *Adjust angles*, or *Refine the

+ question*.

- ```

- Workflow({ scriptPath: "<project>/.claude/workflows/analyze.js", args: <WorkflowArgs> })

- ```

+ ### 3. Run the Dynamic Workflow

- Present a one-line dispatch summary, e.g.:

- `Analyzing "{name}": {topicCount} topics against {goalCount} goals (max {n} rounds) → dynamic-workflow runtime`

+ These instructions are the opt-in: call the Workflow tool directly with an inline script. Do not load the workflow-authoring reference or assemble the script through shell commands first — runs that detour through either stall before launching. Read reference/workflow.md and the four agent references. Author one workflow script that implements

+ the contract exactly, with each agent's prompt taken from its reference and its placeholders filled.

+ Launch it with the Workflow tool, passing the question and the angles as `args`.

- Record the `runId`. The run executes in the background; report status from the run, do not fabricate progress.

+ Choose `model` and `effort` per stage from what the stage does. Stages that fetch and quote sources, or

+ group claims by meaning, can run on a smaller, faster model at lower effort. Tracing a mechanism through

+ code, refuting a claim, and synthesizing the report need the strongest model. A verifier never runs on a

+ weaker model than the researcher whose claim it judges. When unsure, omit `model` so the stage inherits

+ the session model.

- **Hand off at launch.** Once the workflow is dispatched, this thread only relays the run's structured

- return (step 6). Do not keep editing, researching, or holding the plan context open while agents work;

- if the run is backgrounded, end the turn rather than idling on a large prefix.

+ The run executes in the background. Do not research in parallel or fabricate progress.

- ### 6. Report and Finalize

+ ### 4. Present the Report

- When the run returns (`{ name, satisfied, rounds, reportPath, goalResults, grade }`):

+ When the workflow returns (shape in reference/workflow.md):

- 1. Present the report at `reportPath`, plus a per-goal summary (met/unmet from `goalResults`) and the

- report grade — the derived rubric value `grade.overall` and the per-dimension `grade.dimensions`

- scores; list any dimension still scored `fail` or `partial` (with its `grade.issues`) as gaps to close.

- 2. Set `analysis.md` `status: review` if `satisfied`, otherwise leave `in-progress` and call out the

- unmet goals and how to close them (re-run raises `maxRounds` or adds topics).

- 3. Ask the user to choose:

- Mark reviewed (→ `status: done`) | Deepen a goal | Persist report to `docs/research/` | Done

+ 1. If it returns an `error` or no confirmed claims, say so plainly and distinguish an infrastructure

+ failure (verifiers errored — retry) from a negative result (claims refuted on the merits).

+ 2. Otherwise present the summary, each finding with its confidence and sources, the caveats, and the

+ open questions. Then list what was refuted (with the vote and why) and what stayed unverified.

+ 3. Ask the user to *Persist to docs/research/*, *Deepen an open question* (return to step 2 with it as

+ the question), or *Done*.