@siddicky/oh-my-musecode 0.1.0

package/skills/deep-dive/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: deep-dive
+description: Two-stage front door for a fuzzy problem that might be a bug or might be a product question — run trace first to establish what is actually happening, then deep-interview to turn the confirmed problem into a spec. Use ONLY when the user explicitly asks for a deep dive or invokes /deep-dive, typically when they are not yet sure whether the issue is a defect or a scope question. Do NOT use when the nature of the problem is already clear: go straight to /trace for a known bug, or straight to /deep-interview for a known scoping gap.
+---
+
+# Deep Dive
+
+A front door for requests where it is not yet clear whether the real problem
+is "something is broken" or "the scope is unclear." Runs two existing skills
+in sequence rather than duplicating their logic.
+
+Explicit invocation only, like every skill in this corpus. This skill does
+not get triggered by Muse noticing an ambiguous or complex request on its
+own — you invoke it, or the user does.
+
+## When to use this
+
+Use it when a request arrives as something like "this whole area feels off"
+or "users are complaining about X but I don't know if it's a bug or a
+missing feature" — genuine uncertainty about which lane the problem belongs
+in. Do not use it when the lane is already obvious: a reproducible crash
+goes straight to `/trace`; a clear "we need to decide how this should work"
+goes straight to `/deep-interview`. Using this skill on an already-clear
+request just adds a redundant stage.
+
+## Stage 1 — Trace
+
+Read the `trace` skill's body (`read_skill trace` or invoke it directly) and
+run its method against the reported symptom: state the symptom, generate
+competing hypotheses, spawn parallel evidence-gatherers via `subagent_spawn`,
+and converge on a best-evidenced explanation. Do this stage in full — do not
+skip straight to interviewing because the report sounds product-shaped; the
+trace stage is what tells you whether it actually is.
+
+Stop and evaluate after stage 1:
+
+- **Root cause found, fix is small and well-understood** — this is no longer
+  a deep-dive matter. Report the cause and the fix in prose and ask the user
+  whether to apply it. Do not proceed to stage 2 for a confirmed simple bug.
+- **Root cause found, but fixing it right implies a real design decision**
+  (multiple valid approaches, user-facing tradeoffs, or scope beyond the
+  original symptom) — proceed to stage 2.
+- **No clear cause, but the investigation surfaced that the actual ask is
+  underspecified product scope rather than a defect** — proceed to stage 2.
+- **No clear cause and no scope question — genuinely still stuck** — report
+  the trace's evidence table and the next most informative probe. Do not
+  force a transition into stage 2 just to have something to hand off.
+
+## Stage 2 — Deep Interview
+
+Read the `deep-interview` skill's body and run its method, seeded with the
+trace stage's findings: state what was confirmed, what was ruled out, and
+what remains genuinely open. Do not re-ask questions the trace stage already
+answered — hand its evidence in as established fact base, not as unknowns to
+reopen.
+
+Carry the interview through to its own approval gate. Deep-interview owns
+its own spec-writing and approval flow (`.omm/specs/<slug>.md`, explicit
+`Approve`/`Request changes`/`Cancel`); do not shortcut it here.
+
+## State
+
+Trace state and interview state are each owned by their own skill
+(`.omm/state/trace-<slug>.md`, `.omm/specs/<slug>.md`). This skill does not
+introduce a separate state file — it is a sequencing wrapper, not an
+independent stage with its own persistence.
+
+## Handoff
+
+Once the interview stage reaches an approved spec, follow deep-interview's
+own handoff: tell the user in prose to run `/ralplan .omm/specs/<slug>.md`
+next. If stage 1 alone resolved the matter, there is no further handoff —
+say so and stop.

package/skills/deep-interview/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: deep-interview
+description: Run a Socratic interview that turns a vague request into a decision-complete spec, gated by a measured ambiguity score instead of a fixed question count. Use ONLY when the user explicitly asks for a deep interview, invokes /deep-interview, or asks to turn a fuzzy idea into a spec before planning. Do NOT use for ordinary implement/fix/debug requests, for questions with an obvious single answer, or as an automatic first step on complex-looking work — this skill never fires itself; the user or another skill's prose must name it.
+---
+
+# Deep Interview
+
+Convert an ambiguous request into a spec that `ralplan` can plan from, by asking
+targeted questions and tracking how much ambiguity remains after each round.
+
+This skill only runs when explicitly invoked (`/deep-interview`, or a direct user
+ask). Muse never auto-selects a skill because a task looks complex or vague —
+there is no hook or heuristic that fires this skill on your behalf. If you are
+reading this body, something explicitly asked for it.
+
+## When to use this
+
+Use it when the user's goal is real but underspecified: "build something like
+X", "make onboarding better", "port Y into this repo" with no locked scope.
+Do not use it for requests that already have a clear, bounded shape — implement
+those directly. Do not use it merely because a task touches many files; breadth
+is not the same as ambiguity.
+
+## Setup
+
+State lives under `.omm/` at the workspace root — never under `.agents/` or
+`.muse/`, both of which are muse-protected: a mediated `edit_file` write there
+is held for human review with no standing grant, and a shell write fails
+read-only at the sandbox. Create `.omm/specs/` if it does not exist (`.omm/`
+is ordinary unprotected workspace state, so `edit_file` and shell writes both
+work normally).
+
+## Ambiguity model
+
+Track an explicit ambiguity score (0-100%) across rounds, not a fixed question
+budget:
+
+1. Before round 1, enumerate the entities implied by the request (nouns like
+   "user", "state directory", "critic", "acceptance criteria") and mark each
+   Unknown, Assumed, or Locked.
+2. Each round, ask the smallest set of questions (usually 1-3) that would lock
+   the most Unknown/Assumed entities. Prefer questions that collapse several
+   unknowns at once over exhaustive coverage.
+3. After each answer, recompute ambiguity as the fraction of entities still
+   Unknown or Assumed, weighted by how load-bearing each entity is to the
+   final spec (a naming detail counts for less than a topology decision).
+4. Stop asking and move to drafting when ambiguity falls below the configured
+   threshold (default 10%; read `execution.ambiguity_threshold` from muse
+   config if the project sets one, otherwise use the default and say so).
+5. If ambiguity has not measurably dropped for two consecutive rounds, stop
+   the interview and report the stall rather than looping — hand the user a
+   partial spec with the stuck questions listed as open items instead of
+   asking indefinitely.
+
+Optionally probe with a challenge mode for one round when the ontology looks
+too comfortable — a Contrarian round ("what would make this the wrong
+approach entirely?") or a Simplifier round ("what would the smallest version
+that still satisfies the goal look like?"). Use at most one challenge round
+unless the user asks for more; note which mode ran in the spec header.
+
+## Producing the spec
+
+Write the interview's output to `.omm/specs/<slug>.md` with:
+
+- One-sentence goal.
+- Fact base: what was established (from the codebase, from the user, from
+  probing tools) versus assumed.
+- Locked decisions, each with the round it was settled in and why.
+- Any stated-but-unconfirmed assumptions, flagged explicitly.
+- Acceptance criteria the eventual implementation must satisfy.
+- Final ambiguity percentage and threshold used.
+
+Do not silently invent scope to fill a section. If a section has nothing real
+to say (no risks, no deferred items), write "None" rather than padding it.
+
+## Explicit approval gate
+
+Present the complete spec in a normal reply and ask the user to `Approve`,
+`Request changes`, or `Cancel`. Do not treat silence, a topic change, or your
+own confidence as approval. On `Request changes`, revise the same spec file
+and re-present it. On `Cancel`, stop and leave the spec file as a draft,
+clearly marked unapproved at the top.
+
+## Handoff
+
+This skill does not chain into the next stage automatically — nothing in Muse
+reads a "next-skill" field from frontmatter; that field does not exist here.
+Once the spec is approved, say so in plain prose and tell the user the next
+step in the pipeline: "Spec approved and saved to `.omm/specs/<slug>.md`. Run
+`/ralplan .omm/specs/<slug>.md` next to turn this into a plan." Then stop.
+Do not start planning or implementation yourself from inside this skill.
+
+## Notes on personas
+
+If parts of the interview benefit from a second perspective (for example,
+probing technical feasibility of a locked decision), you may
+`subagent_spawn` the `architect` or `explore` persona with a narrow objective
+and read its result back with `subagent_read_result` before continuing the
+interview. These are prompt personas rendered into the spawn call, not muse
+Agent Definitions — muse rejects `agents` as a plugin capability, so no
+persona is registered as a first-class agent type.

package/skills/ralph/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: ralph
+description: Run a PRD-driven implementation loop against .omm/state/prd.json, iterating story by story until every acceptance criterion passes, then a final reviewer verification pass. Use ONLY when explicitly invoked (/ralph) against an approved PRD, normally right after /ralplan. Do NOT use without an approved prd.json (run /ralplan first), and do not invoke this for a single small edit — the loop overhead only pays for itself across multiple testable stories.
+---
+
+# Ralph
+
+Execute an approved PRD to completion: iterate its stories, implement each
+one, verify its acceptance criteria, and loop until all pass or the loop
+cannot make further progress. Named for the self-referential "Ralph Wiggum"
+loop pattern — run the same verification cycle until it stops finding
+problems, not for a fixed number of turns.
+
+Explicit invocation only. This skill does not start itself when `ralplan`
+finishes — ralplan's own body tells the user to invoke `/ralph` next in
+prose; nothing in frontmatter chains them.
+
+## Precondition
+
+Require `.omm/state/prd.json` to exist and be approved (per `ralplan`'s
+gate). If it is missing, stop and tell the user to run `/ralplan` first —
+do not improvise a PRD inline just to proceed.
+
+## Loop
+
+For each story in `prd.json` with `status: "pending"`, in order unless the
+PRD marks explicit parallelizable groups:
+
+1. Set the story `status` to `"in_progress"` in `prd.json`.
+2. Implement the story's described change directly, or delegate to the
+   `executor` persona via `subagent_spawn("executor", <story objective +
+   acceptance criteria>, worktree_isolation: true)` when the story is large
+   enough to isolate — worktree isolation matters here specifically because
+   multiple ralph iterations or a parallel `team` run may be touching the
+   same repo; an isolated worktree keeps one story's half-finished edits
+   from bleeding into another's verification.
+3. Check every acceptance criterion for that story against real evidence —
+   run the command it names, inspect the output, do not mark a criterion
+   passed on the basis of "this should work." A criterion that cannot be
+   checked as written is a defect in the PRD, not a license to skip it;
+   fix the criterion's wording in `prd.json` and say so, rather than
+   silently treating it as satisfied.
+4. If all criteria pass, set `status: "done"` and record what evidence
+   confirmed each criterion. If any fail, keep `status: "in_progress"`,
+   record what failed, and retry the implementation step. Cap retries per
+   story (default 3) — after the cap, mark `status: "blocked"` with the
+   failure detail and move to the next story rather than looping forever on
+   one blocker.
+5. Move to the next pending story.
+
+Stop the loop when every story is `"done"` or `"blocked"`. A run that ends
+with any `"blocked"` story is not complete — report it as such.
+
+## Reviewer verification pass
+
+Once the loop ends with no pending stories, run a separate verification pass
+— never self-approve inside the same implementation context that just wrote
+the code:
+
+- Default: `subagent_spawn("verifier", "verify every done story in
+  .omm/state/prd.json against its acceptance criteria with independent
+  evidence")`, then read its result.
+- **`--critic=codex` or `--critic=claude` option.** Route this verification
+  pass through the named external CLI instead. This requires the session to
+  have been launched with `muse --disable-sandbox` (or `--yolo`). If it was
+  not, stop and tell the user rather than quietly downgrading to the
+  in-process verifier, since that is a materially different check.
+
+  **State the tradeoff plainly, every time this option is used, not just
+  once at setup.** Two distinct costs, and neither should be blurred into
+  the other:
+
+  1. The external critic's work happens outside Muse's append-only audit
+     trail. Its reasoning and any files it touches are not captured the way
+     an in-session `subagent_spawn` result is.
+  2. The escalation is **session-wide, not scoped to the critic call**.
+     `--disable-sandbox` removes filesystem and network sandboxing for
+     everything in that session, not just the one process that needed it.
+
+  There is no narrower route on this build: muse 1.0.3 exposes no way to
+  create a named permission profile (`muse exec --permission-profile <id>`
+  reports `profile does not exist`, and `execution.permission_profiles`
+  validates as `field_not_activated`). So the broad carve-out is the whole
+  cost of the external critic, not an implementation shortcut. This is a
+  deliberate, user-reaffirmed tradeoff — it buys genuine cross-model
+  adversarial review — but say as much in the final report rather than
+  letting it pass unmentioned.
+
+## Enterprise policy interaction
+
+If the workspace's execution policy sets `execution.forbid_sandbox_bypass`,
+`--disable-sandbox` and `--yolo` are refused and the external critic cannot
+run at all, regardless of `--critic`. Fail with a clear message naming the
+policy and the blocked step — do not silently fall back to the in-process
+critic/verifier and present it as if the requested external check ran.
+
+## Completion report
+
+Report, per story: id, final status, and the evidence that justified it.
+Report the verification pass's mode (in-process or external) and its
+verdict. If any story ended `"blocked"`, list it prominently — do not bury a
+blocked story under a headline "done."
+
+## Handoff
+
+Ralph is a terminal stage in this pipeline. There is nothing further to
+chain to automatically; report completion (or the blocked/failed state) and
+stop. If new scope surfaces during implementation that the PRD did not
+cover, say so in prose and suggest the user run `/deep-interview` or
+`/ralplan` again for that new scope — do not silently fold unplanned work
+into the current loop.

package/skills/ralplan/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: ralplan
+description: Turn an approved spec into a consensus-reviewed plan with a PRD (prd.json) of testable stories, gating vague /ralph or /team requests before they run unattended. Use ONLY when explicitly invoked (/ralplan), typically right after deep-interview hands off a spec, or when the user asks to plan before a ralph/team run. Do NOT use for direct small edits, and do not treat an invocation of /ralph or /team as implicitly requesting this — ralplan only runs when named.
+---
+
+# Ralplan
+
+Convert an approved spec (or a request specific enough to skip straight to
+planning) into a `prd.json` of testable stories, reviewed for consensus
+before `ralph` is allowed to run unattended against it.
+
+Explicit invocation only — there is no hook that auto-routes a vague `/ralph`
+or `/team` request into this skill. If you want that gating, say so in
+prose to the user yourself: "this looks underspecified for an unattended
+ralph run — recommend `/ralplan` first," and let the user decide.
+
+## Inputs
+
+- An approved spec at `.omm/specs/<slug>.md` (preferred), or
+- A request detailed enough to plan directly, when the user explicitly says
+  to skip the interview stage.
+
+## Producing the PRD
+
+Write `.omm/state/prd.json` (create `.omm/state/` if missing) shaped as:
+
+```json
+{
+  "goal": "one sentence",
+  "source_spec": ".omm/specs/<slug>.md",
+  "stories": [
+    {
+      "id": "US-001",
+      "title": "short title",
+      "description": "what this story delivers",
+      "acceptance_criteria": [
+        "testable, falsifiable statement",
+        "another testable statement"
+      ],
+      "status": "pending"
+    }
+  ]
+}
+```
+
+Every story's acceptance criteria must be testable by inspection, command
+output, or reproducible check — not by opinion. "Code is cleaner" is not a
+valid criterion; "muse skills validate <path> reports valid: true with zero
+unsupported-skill-field diagnostics" is. `ralph` will iterate against this
+file story by story, so vague criteria become the loop's failure mode later.
+
+## Consensus review
+
+Before presenting the plan, get a second opinion:
+
+1. Default reviewer is the `critic` persona in-process:
+   `subagent_spawn("critic", "review prd.json at .omm/state/prd.json against
+   the spec for gaps, untestable criteria, and scope creep")`, then
+   `subagent_wait` / `subagent_read_result`.
+2. **`--critic=codex` or `--critic=claude` option.** When the user passes
+   this, route the review through the named external CLI instead of the
+   in-process critic persona. This requires the session to have been
+   launched with `muse --disable-sandbox` (or `--yolo`) — say so explicitly
+   if it was not, and stop rather than silently falling back to the
+   in-process critic, since that changes what was actually reviewed.
+
+   **Be honest about the tradeoff.** Shelling out to an external `codex` or
+   `claude` CLI process costs two separate things. First, that review's work
+   happens outside Muse's append-only audit trail — the external process's
+   reasoning and any files it touches are not captured the way an in-session
+   `subagent_spawn` result is. Second, the escalation is session-wide:
+   `--disable-sandbox` removes filesystem and network sandboxing for
+   everything in the session, not just the critic call.
+
+   There is no narrower route on muse 1.0.3 — named permission profiles are
+   not creatable on this build — so the broad carve-out is the actual price
+   of an external critic. State this plainly in the review summary; do not
+   soft-pedal it as equivalent to the in-process critic.
+3. Incorporate the critic's findings into the PRD before presenting it.
+   Untestable criteria, missing stories implied by the spec, and scope the
+   critic flags as unjustified should be fixed, not just noted.
+
+## Approval gate
+
+Present the final `prd.json` contents (or a readable summary of every story
+and its criteria) in a normal reply, state which critic mode reviewed it,
+and ask for `Approve`, `Request changes`, or `Cancel`. Do not let `ralph`
+start from an unapproved PRD.
+
+## Handoff
+
+On approval, say in prose: "PRD approved at `.omm/state/prd.json`. Run
+`/ralph` next (add `--critic=codex` or `--critic=claude` to keep the same
+external reviewer for verification, and remember that needs the session
+launched with `muse --disable-sandbox`)." There is no frontmatter field that
+wires this handoff automatically — it exists only because this body says it.

package/skills/team/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: team
+description: Run N coordinated persona subagents in parallel against a shared task list, each isolated in its own worktree, for work that splits cleanly into independent units. Use ONLY when explicitly invoked (/team) for genuinely parallelizable work — several independent files, stories, or investigations with no shared-state conflicts. Do NOT use for a single sequential task, for work with heavy cross-file coupling that would fight worktree isolation, or as an automatic response to "this is a big task."
+---
+
+# Team
+
+Coordinate multiple persona subagents working in parallel on a shared task
+list, each isolated in its own worktree so simultaneous writers do not
+collide on the same files.
+
+Explicit invocation only. Nothing infers that a task "is big enough" to
+warrant a team on its own — you decide that and invoke `/team`, or another
+skill's prose (such as `ralph`, for a PRD with an explicit parallel group)
+tells the user to.
+
+## When to use this
+
+Use it when the task list has real independence: separate stories, separate
+files or modules, separate investigations that do not need to see each
+other's intermediate state. Do not use it when tasks are tightly coupled —
+sequential work through one context (or a single `ralph` loop) is both
+simpler and avoids merge friction. Do not use it for a task list of one.
+
+## Building the task list
+
+Source the task list from, in order of preference:
+1. An explicit list the user gives in the invocation.
+2. `.omm/state/prd.json`, if it declares an explicit parallel group (see
+   `ralph`) — use exactly that group, not the whole PRD.
+3. A list you derive directly from the request, stated back to the user
+   before spawning anything if it required real judgment to split.
+
+Each task needs: an id, a scope narrow enough for one persona to own without
+touching another task's files, and a definition of done.
+
+## Spawning
+
+For each task, choose the persona that fits its shape (`executor` for
+implementation, `test-engineer` for test work, `writer` for docs,
+`debugger` for isolated bug fixes, etc.) and:
+
+```
+subagent_spawn(role, objective, worktree_isolation: true)
+```
+
+Always set `worktree_isolation: true` for team members that write files —
+this is the mechanism that keeps parallel writers from stepping on each
+other; without it, concurrent edits to overlapping files are a real risk,
+not a hypothetical one. Read-only investigation tasks may skip isolation if
+they touch nothing.
+
+Track every spawned id against its task. Do not spawn more than the
+session's concurrent-child limit at once (muse caps concurrent subagent
+children); queue remaining tasks and spawn the next as a slot frees up
+rather than firing them all and hoping.
+
+## Coordination
+
+- Poll with `subagent_status` / `subagent_wait` rather than assuming
+  completion order matches spawn order.
+- If one task's output changes what another in-flight task should do, use
+  `subagent_send_message` to update it rather than letting it finish on a
+  stale premise.
+- If a task is no longer needed (superseded by another's findings, or the
+  user narrows scope mid-run), `subagent_cancel` it explicitly rather than
+  leaving it to finish pointless work.
+- Read every terminal result with `subagent_read_result` before reporting —
+  a `subagent_wait` timeout is not a terminal state; keep waiting or check
+  status again rather than treating a timeout as failure.
+
+## Merging results
+
+Worktree isolation means each task's changes live in its own worktree until
+merged. Review each task's diff before merging — do not merge blind because
+the subagent reported success. Merge in an order that respects real
+dependencies between tasks (a task that renamed a shared interface merges
+before tasks that consume it, even if it finished later). Surface merge
+conflicts to the user rather than silently picking a resolution when the
+conflict touches logic, not just formatting.
+
+## Completion report
+
+Report per task: id, persona used, terminal status, whether its worktree was
+merged, and any conflicts or cancellations. If any task is blocked or
+failed, list it prominently rather than only reporting the successes.
+
+## Handoff
+
+Team has no fixed successor — what comes next depends on what the parallel
+work was for. If it was a `ralph` parallel group, say so and return control
+to the ralph loop's per-story verification. Otherwise, state completion and
+let the user decide the next step; do not chain into another skill on your
+own initiative.

package/skills/trace/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: trace
+description: Investigate a specific observed problem (a bug, a regression, an unexpected behavior) by running competing tracer hypotheses in parallel and converging on the best-evidenced explanation. Use ONLY when the user explicitly asks to trace, diagnose, or root-cause a concrete symptom, or invokes /trace. Do NOT use for vague goal-shaping ("make this better") — that belongs to deep-interview — and do not use it for routine debugging you can resolve with a single direct read; this skill is for when the cause is genuinely unclear and evidence needs to be gathered from multiple angles at once.
+---
+
+# Trace
+
+Find the real cause of an observed problem by running multiple competing
+hypotheses against evidence in parallel, instead of debugging serially under
+one assumption.
+
+Explicit invocation only. Nothing in Muse decides on its own that a bug
+"looks hard enough" to warrant this skill — you or the user must name it
+directly, or another skill's prose must tell the user to invoke it (see
+`deep-dive`, which routes here first).
+
+## When to use this
+
+Use it when: the symptom is clear (a failing test, a wrong output, a crash,
+a regression between two known-good points) but the cause is not, and a
+single obvious read of the code will not settle it. Do not use it for a bug
+whose cause is already apparent from the error message or a quick grep —
+just fix that directly. Do not use it for open-ended product questions;
+route those to `deep-interview` instead.
+
+## Setup
+
+Write working state to `.omm/state/trace-<slug>.md` (create `.omm/state/` if
+missing). Never write trace scratch files under `.agents/` or `.muse/` —
+both are muse-protected paths that reject unmediated writes.
+
+## Method
+
+1. **State the symptom precisely.** Exact observed behavior, exact expected
+   behavior, and the smallest reproduction you have. If you cannot state a
+   precise symptom, this is not ready for tracing — ask the user to narrow
+   it or fall back to ordinary debugging.
+2. **Generate competing hypotheses.** List 2-4 genuinely different candidate
+   causes, not variations on the same guess. Each hypothesis should predict
+   a different piece of evidence if true.
+3. **Spawn parallel evidence-gatherers.** For each hypothesis, `subagent_spawn`
+   an `explore` or `debugger` persona with an objective narrowly scoped to
+   confirming or falsifying that one hypothesis — not to fixing anything.
+   Use `worktree_isolation` only if a hypothesis requires running code with
+   local mutations; pure read/grep investigation does not need it. Track the
+   spawned ids and poll with `subagent_status`/`subagent_wait`.
+4. **Collect evidence, not verdicts.** Read each result with
+   `subagent_read_result`. Record what was found for and against each
+   hypothesis, including negative results — a hypothesis a subagent could not
+   confirm is evidence too.
+5. **Score and converge.** Rank hypotheses by evidence weight. If one
+   hypothesis is clearly best-supported, state it and the confirming
+   evidence. If two remain close, say so plainly rather than picking one to
+   look decisive — an honest "still ambiguous between A and B, next probe
+   would be X" is a valid outcome of this skill.
+6. **Recommend the next probe or the fix.** If the cause is confirmed,
+   describe the fix (do not apply it unless the user also asked for a fix in
+   the same request). If not confirmed, name the single most informative
+   next piece of evidence to gather.
+
+## Output
+
+Write the hypothesis table (hypothesis, evidence for, evidence against,
+verdict) to the state file, then present it in a normal reply. Keep it
+evidence-first: a hypothesis with no cited evidence is not a valid entry in
+the table.
+
+## Handoff
+
+Trace does not automatically start a fix or hand off to another skill; there
+is no frontmatter mechanism to chain skills. If the traced cause implies real
+scope decisions (not just a one-line fix), say in prose: "Cause identified —
+this touches enough surface that it's worth a spec before changing anything.
+Run `/deep-interview` next if you want that, or ask me to apply the fix
+directly." Then stop and let the user choose.