@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/filter-search-matrix.md

@@ -0,0 +1,66 @@
+# Filter/Search Coverage Matrix
+
+> Master Matrix — per-platform support for each filter/search dimension.
+> Ships with the skill. Updated by PRs when platform support changes.
+> For unknown platforms: runtime CLI docs lookup (see adapter-strategy.md Q6).
+
+## Dimension definitions
+
+| Dimension | What it filters/searches |
+|-----------|-------------------------|
+| by agent ID | Traces from a specific agent identifier |
+| by session ID | A specific session/trace ID |
+| by time window | Traces in a time range |
+| by score | Traces with score above/below threshold |
+| has feedback | Traces with any attached feedback |
+| has error | Traces containing error events |
+| latency P99 | Traces with high latency |
+| by route / trace name | Traces with a specific operation name |
+| by tag | Traces with specific labels/tags |
+| by skill | Traces where a specific skill was triggered |
+| Search: full-text | Content-level search in trace messages |
+| Search: semantic | Semantic similarity search |
+
+---
+
+## Coverage Matrix
+
+| Dimension | Langfuse | OTel | local-jsonl | claude-code | codex |
+|-----------|----------|------|-------------|-------------|-------|
+| by agent ID | `--agent-id` CLI flag | `span.attr[gen_ai.agent.id]` | post-filter on `agentId` field | filename pattern or content grep | grep `agent_type` field in rollout JSONL |
+| by session ID | `--session-id` CLI flag | `trace_id` | post-filter on `sessionId` field | filename = session-id | filename = session-id in `~/.codex/sessions/` |
+| by time window | `--from` / `--to` CLI flags | span `startTime` / `endTime` | post-filter on `startTime` timestamp | file `mtime` (`find -newer`, `-newer`) | file `mtime` in `~/.codex/sessions/` |
+| by score | `--score-below` / `--score-above` flags | partial — depends on emitter | if `score` field present | limited — only `/feedback` thumbs (discrete boolean) | limited — check rollout for custom score field |
+| has feedback | `--has-feedback` flag | partial — depends on emitter | if `hasFeedback` field present | limited — check for `/feedback` approval events | via `approval` events in rollout JSONL |
+| has error | `--has-error` flag | `span.status.code == 2 (ERROR)` | post-filter on `hasError` field | grep `isError: true` in tool_result events | grep `error` events in rollout JSONL |
+| latency P99 | native aggregation | compute from span `duration` | compute from `startTime`/`endTime` | derive from event timestamps | derive from event timestamps in rollout |
+| by route / trace name | `--name` flag | span `name` field | partial — if `route` field present | n/a (single-route per session) | n/a (single-thread) |
+| by tag | `--tag` flag | `span.attr[tags]` | partial — if `tags` field present | n/a | n/a |
+| by skill | via tag/metadata (`--tag skill:<name>`) | via `span.attr[skill]` | grep `skill` metadata field | grep `Skill` tool calls in JSONL | grep skill invocations in rollout events |
+| Search: full-text | partial — via SDK filter, not CLI | no — post-fetch grep required | grep over jsonl lines | grep over session jsonl lines | grep over rollout jsonl lines |
+| Search: semantic | no | no | no | no | no |
+
+---
+
+## Lookup strategy
+
+### Known platforms (Langfuse, OTel, local-jsonl, claude-code, codex)
+
+Use the Master Matrix above. Reference doc for each platform has concrete CLI examples.
+
+### Unknown / custom platforms
+
+Agent does **runtime CLI docs lookup**:
+1. `Bash("<cli> --help")` — read help text
+2. `WebFetch(upstream-docs-url)` — fetch from the URL in `references/source-platforms/<name>.md`
+3. Reason over help text → map dimensions to CLI flags
+
+If mapping is ambiguous, surface to operator via AskUserQuestion.
+
+---
+
+## Notes
+
+- **Semantic search**: not supported on any platform in v0.1. Post-v0.1 consideration.
+- **Codex score support**: Codex doesn't ship a feedback primitive natively. Check `codex-rs/rollout/src/lib.rs` for custom score fields if the operator's Codex build includes them.
+- **Claude Code score**: limited to `/feedback` approval (thumbs-up/down boolean). Scale type = `boolean`. Negative = `false`/`"down"`.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/harness-knowledge.md

@@ -0,0 +1,22 @@
+# Platform Knowledge Table
+
+> Expandable table. Static info ships with the skill.
+> Runtime details (latest CLI flags, current API endpoints) recovered via the linked upstream docs.
+> Add new harnesses by submitting a PR to this file.
+
+| Harness | Transcript path (static) | ASK primitive | Schedule primitive | Upstream docs |
+|---------|--------------------------|---------------|-------------------|---------------|
+| **Claude Code** | `~/.claude/projects/<encoded-path>/<session-id>.jsonl` (plaintext JSONL; 30-day default retention via `cleanupPeriodDays`) | `AskUserQuestion` tool — structured multi-select, `preview` attr for code/diff comparisons. Native. | Native `/loop` + `CronCreate` + `ScheduleWakeup` tools. | [code.claude.com/docs](https://code.claude.com/docs/en/) |
+| **Codex CLI** | `~/.codex/sessions/<session>.jsonl` (active) + `~/.codex/archived_sessions/<session>.jsonl` (archived). Config: `~/.codex/config.toml`. Constants `SESSIONS_SUBDIR="sessions"` + `ARCHIVED_SESSIONS_SUBDIR="archived_sessions"` in `codex-rs/rollout/src/lib.rs`. Default-on; suppress with `codex exec --ephemeral`. | Approval prompts via TUI (Windows toast fallback). No structured-picker tool primitive yet — chat-based multi-choice. | External cron + `codex exec` for non-interactive runs. No native scheduler. | [developers.openai.com/codex](https://developers.openai.com/codex/cli) · [codex-rs/rollout source](https://github.com/openai/codex/tree/main/codex-rs/rollout) |
+| **Cursor** | Local SQLite under VSCode-style workspace storage (e.g. `~/Library/Application Support/Cursor/User/workspaceStorage/<hash>/state.vscdb` on macOS). Verify at runtime via probe. | Chat-based confirmation. No public structured-picker tool surfaced. | Background Agents (2025+) — autonomous task primitive; verify scheduling support at runtime. | [cursor.com/docs](https://cursor.com/docs) |
+| **OpenCode** | Path TBD — runtime probe at onboarding. | Chat-based (Plan mode + general prompting). | None documented — use OS cron. | [opencode.ai/docs](https://opencode.ai/docs) |
+| *Add more harnesses here* | *operator adds rows over time* | | | |
+
+---
+
+## Notes
+
+- **Encoding of Claude Code project paths**: Claude Code encodes the absolute project path into the directory name under `~/.claude/projects/`. The encoding is an internal detail — `cli/init.ts` probes by trying known encodings and falls back to listing all project dirs.
+- **Codex paths confirmed iter-8**: path confirmed from `codex-rs/rollout/src/lib.rs` source constants. If paths change in a future Codex release, update this table and the Codex adapter in `@mutagent/tools` (`mutagent-cli trace fetch --platform codex` — the skill no longer owns a Codex normalizer post-UniTF-flip).
+- **Semantic search**: not supported on any harness in v0.1.
+- **Schedule recovery**: platform scheduling specifics (exact API, cron syntax, daemon setup) are recovered at runtime by the agent via the upstream docs links above. This table stores only static facts.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/memory-format.md

@@ -0,0 +1,78 @@
+# AutoMemory Format — project-level operator-feedback + tool-lessons
+
+> **Standard (mirrored across ADL skills — parity).** The subject of AutoMemory is
+> the **TOOL + operator preferences**, NOT the diagnosed agent (that is the
+> gitignored class-memory library). ONE project-level store for the whole lifecycle.
+> Fixed convention + standardized format; NOT a config field.
+>
+> Read/write helpers: `scripts/memory/read.ts` + `scripts/memory/append.ts`.
+
+## Location + shape
+
+```
+.mutagent/memory/                    ← project-level, COMMITTED
+  MEMORY.md                          ← index: `- [Title](<slug>.md) — <hook>` one line/entry
+  <slug>.md                          ← one FACT per file
+```
+
+Each `<slug>.md` entry — Claude-Code AutoMemory format (verbatim):
+
+```markdown
+---
+name: <short-kebab-case-slug>
+description: <one-line summary — used to decide relevance during recall>
+metadata:
+  type: user | feedback | project | reference    # Claude Code's four types
+  lifecycle: spec|build|evaluate|diagnose|improve|general   # ADL extension
+  created: YYYY-MM-DD                             # REQUIRED · every memory is DATED (stale-pruning)
+---
+
+<the fact. For feedback/project: **Why:** + **How to apply:** lines. Link with [[their-name]].>
+```
+
+- **Every entry DATED** (`metadata.created`). The date is an ABSOLUTE `YYYY-MM-DD`
+  (injected `now` for determinism in `appendMemory`).
+- `MEMORY.md` is an **index only** — one `- [Title](<slug>.md) — <hook>` line per
+  entry, sorted by slug. The `<hook>` is the entry's `description`.
+- **Dedupe on append**: an existing slug is UPDATED in place and its `created` date
+  REFRESHED (never a duplicate file).
+
+## Feedback → type CLASSIFICATION rubric (verbose)
+
+Decision order — **first match wins**:
+
+| # | Feedback about… | → type | Signals | Body |
+|---|---|---|---|---|
+| 1 | external resource | `reference` | URL · dashboard · ticket · dataset path | pointer + what it's for |
+| 2 | who the operator is | `user` | "I'm the lead" · standing preference | the trait |
+| 3 | how the tool should behave | `feedback` | "stop surfacing X" · "too verbose" · "next time…" | fact + **Why:** + **How to apply:** |
+| 4 | ongoing work/goals/constraints | `project` | "migrating to…" · "don't touch Z until…" | fact + **Why:** + **How to apply:** |
+
+**Do NOT save:**
+- Anything already in code / config / git (it is already the source of truth).
+- Ephemeral facts relevant to only ONE run.
+- Subject FINDINGS about the diagnosed agent (those go to the class-memory library
+  `.mutagent/diagnostics/library/`, gated by operator approval — NOT here).
+
+## Lifecycle filter at recall
+
+At run START (parse-brief / Step 3a) the diagnostics run loads memory FILTERED to
+`lifecycle ∈ { diagnose, general }` (`readDiagnoseMemory`) — the diagnostics stage's
+own lessons plus the always-relevant `general` facts. Entries tagged for other
+stages (`spec` / `build` / `evaluate` / `improve`) are skipped for a diagnose run.
+
+## When to append (write trigger)
+
+At run FINALIZE (finalize-gate / Step 9.9), when the operator gives feedback ABOUT
+the tool or a standing preference, classify it with the rubric above and call
+`appendMemory({ slug, name, description, type, lifecycle, body, now })`. The default
+`lifecycle` for diagnostics-run feedback is `diagnose` (use `general` for a
+tool-wide standing preference).
+
+## Memory subsystems (NOT competing — different subjects)
+
+| Subsystem | Subject | Content | Write trigger | Location |
+|---|---|---|---|---|
+| **Class-memory library** | diagnosed entity | journal + regex patterns + deep-read ledger | operator-APPROVED findings only | `.mutagent/diagnostics/library/…` · gitignored |
+| **feedback_sources** | diagnosed entity | external signals → enrich findings | read-only, per-run | opt-in config |
+| **AutoMemory** (this doc) | the tool + operator | usage-feedback + lessons (Claude format, dated, classified) | operator feedback | `.mutagent/memory/` · committed |

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/onboarding-decisions.yaml

@@ -0,0 +1,187 @@
+# references/onboarding-decisions.yaml
+# R-SELF-07-a: Structured option lists for each onboarding decision phase.
+# Used by the parent session (inline orchestrator) when presenting choices to the operator.
+#
+# Each decision has:
+#   id        — machine ID for the choice
+#   label     — human-readable label shown to operator
+#   value     — written to config.yaml when chosen
+#   platform_doc — (optional) references/source-platforms/{value}.md path to load
+#   note      — (optional) rendered below the option if selected
+#
+# R-SELF-07-b: Every option list MUST end with the Custom escape hatch entry
+#   { label: 'Custom — describe what you have', value: '__custom__' }
+# so the operator is never blocked on an unsupported platform.
+
+version: "1.0"
+
+decisions:
+
+  # Phase 1 — Source platform
+  source_platform:
+    question: "Where do your agent traces live?"
+    key: source_platform
+    options:
+      - id: langfuse
+        label: "Langfuse (cloud or self-hosted)"
+        value: langfuse
+        platform_doc: "references/source-platforms/langfuse.md"
+      - id: otel
+        label: "OpenTelemetry-compliant endpoint"
+        value: otel
+        platform_doc: "references/source-platforms/otel.md"
+      - id: local-jsonl
+        label: "Local trace file (.jsonl / .ndjson)"
+        value: local-jsonl
+        platform_doc: "references/source-platforms/local-jsonl.md"
+      - id: claude-code
+        label: "Claude Code local transcripts (~/.claude/projects/…/*.jsonl)"
+        value: claude-code
+        platform_doc: "references/source-platforms/claude-code.md"
+      - id: codex
+        label: "Codex local transcripts (~/.codex/sessions/*.jsonl)"
+        value: codex
+        platform_doc: "references/source-platforms/codex.md"
+      - id: __custom__
+        label: "Custom — describe what you have"
+        value: __custom__
+        note: "Describe your trace format. Orchestrator will attempt a general-purpose fallback and guide credential setup."
+
+  # Phase 4 — Target platform (where agent definitions live)
+  target_platform:
+    question: "Where do your agent definitions live?"
+    key: target_platform
+    options:
+      - id: local-claude
+        label: "Claude Code agents (.claude/agents/*.md)"
+        value: local-claude
+        platform_doc: "references/target-platforms/local-claude.md"
+      - id: local-codex
+        label: "Codex agents (.codex/agents/*.md)"
+        value: local-codex
+        platform_doc: "references/target-platforms/local-codex.md"
+      - id: local-cursor
+        label: "Cursor agents (cursor-equivalent dir)"
+        value: local-cursor
+        platform_doc: "references/target-platforms/local-cursor.md"
+      - id: local-opencode
+        label: "OpenCode agents (opencode-equivalent dir)"
+        value: local-opencode
+        platform_doc: "references/target-platforms/local-opencode.md"
+      - id: mastra
+        label: "Mastra code construct (source code: new Agent({...}))"
+        value: mastra
+        platform_doc: "references/target-platforms/mastra.md"
+      - id: anthropic-cloud
+        label: "Anthropic Cloud Agent SDK (source code)"
+        value: anthropic-cloud
+        platform_doc: "references/target-platforms/anthropic-cloud.md"
+      - id: rest-api
+        label: "Cloud REST API (HTTP GET/PUT)"
+        value: rest-api
+        platform_doc: "references/target-platforms/rest-api.md"
+      - id: __custom__
+        label: "Custom — describe where your agents live"
+        value: __custom__
+        note: "Describe your agent storage format. Orchestrator will attempt the general-purpose code-construct apply path."
+
+  # Phase 5b agent install scope
+  agent_install_scope:
+    question: "Install diagnostics-* agents: project-scope or user-global?"
+    key: agent_install_scope
+    options:
+      - id: project
+        label: "Project-scope (recommended — visible in repo's .claude/agents/)"
+        value: project
+        note: "Writes to $PROJECT_ROOT/.claude/agents/ — committed, visible to all contributors."
+      - id: user
+        label: "User-global (~/.claude/agents/ — available in all projects)"
+        value: user
+        note: "Writes to ~/.claude/agents/ — not in repo, convenient for personal setups."
+      - id: __custom__
+        label: "Custom path — specify manually"
+        value: __custom__
+        note: "You will be prompted for the exact destination directory."
+
+  # Phase 5c dry-spawn verification offer
+  agent_dry_spawn:
+    question: "Agents verified. Want to dry-spawn each with a no-op probe?"
+    key: agent_dry_spawn
+    options:
+      - id: yes
+        label: "Yes — probe all 3 (safe: no trace data read, no writes)"
+        value: yes
+        note: "Dispatches each agent with prompt: 'echo: probe' and confirms they activate."
+      - id: no
+        label: "No — skip, I trust the verification"
+        value: no
+      - id: __custom__
+        label: "Custom — probe only specific agents"
+        value: __custom__
+        note: "Specify which agents to probe by name."
+
+  # Phase 6 — Trigger rules
+  # ⏸ DISABLED for v0.1: do NOT ask this question. v0.1 is always on-demand.
+  #    Auto-write `schedule.mode: on-demand` without prompting. Re-enable (flip
+  #    disabled: false) when scheduling lands post-v0.1. Config field is KEPT.
+  trigger_mode:
+    disabled: true
+    default: on-demand
+    question: "When should diagnostics run?"
+    key: schedule.mode
+    options:
+      - id: on-demand
+        label: "On-demand (I invoke it manually) — recommended for v0.1"
+        value: on-demand
+      - id: scheduled
+        label: "I'll set up scheduling later (structure prepared)"
+        value: on-demand
+        note: "Config will contain schedule.mode: on-demand. Edit references/workflows/schedule-prep.md to wire scheduling post-v0.1."
+      - id: __custom__
+        label: "Custom — describe your trigger"
+        value: __custom__
+        note: "Orchestrator will translate your description into a trigger rule. May require schedule.mode: scheduled."
+
+  # Phase 6 — Trigger condition
+  trigger_condition:
+    question: "Add a trigger condition? (optional)"
+    key: trigger_condition
+    options:
+      - id: score-threshold
+        label: "Diagnose when score < threshold (threshold auto-discovered)"
+        value: score-threshold
+      - id: error-rate
+        label: "Diagnose when error rate > 20%"
+        value: error-rate
+      - id: none
+        label: "No trigger condition — manual invocation only"
+        value: none
+      - id: __custom__
+        label: "Custom filter — describe in natural language"
+        value: __custom__
+        note: "Orchestrator will translate your description into a TraceFilter."
+
+  # Phase 8 — First-run pick
+  first_run:
+    question: "Setup complete! What would you like to diagnose first?"
+    key: first_run
+    options:
+      - id: last-24h
+        label: "Diagnose traces from the last 24 hours"
+        value: last-24h
+      - id: most-recent-failing
+        label: "Diagnose your most recently failing agent"
+        value: most-recent-failing
+      - id: negative-feedback-week
+        label: "Diagnose all sessions with negative feedback this week"
+        value: negative-feedback-week
+      - id: high-latency
+        label: "Diagnose all high-latency sessions"
+        value: high-latency
+      - id: manual
+        label: "I'll invoke manually later"
+        value: manual
+      - id: __custom__
+        label: "Custom — describe what you want to diagnose"
+        value: __custom__
+        note: "Orchestrator will translate your description into a TraceFilter."

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/operation-inventory.md

@@ -0,0 +1,59 @@
+# Operation Inventory — Type A/B/C Classification
+
+> Per PR-019. Every operation is exactly one type. No overlap.
+> Used as the audit surface for code review of new contributions.
+
+## Classification Rules
+
+- **Type A — Pure Script**: deterministic logic, structured I/O. Written in TypeScript, invoked via `Bash("scripts/cli/run.sh scripts/<name>.ts ...")`. Zero LLM calls. Testable in isolation.
+- **Type B — Agent Operation**: uses agent's native tools (Bash for external CLI, Agent for sub-dispatch, AskUserQuestion/equivalent for HITL, Read/Edit/Write for files). LLM reasoning. Cannot be unit tested in isolation.
+- **Type C — Hybrid**: agent invokes a Type A script, passes structured input, reads structured output. Script provides deterministic shape; agent decides when/how to invoke it.
+
+---
+
+## Type A — Pure Scripts (9 scripts, 2 self-diagnostics)
+
+| Op | File | Why script |
+|----|------|-----------|
+| Tier 0 static scan | `scripts/tier0-scan.ts` | Deterministic pattern matching + signal counts |
+| Trace slicing | `scripts/slicer.ts` | Deterministic math + cap-of-5 clustering |
+| Config load | `scripts/config/load.ts` | YAML parse + env lookup |
+| Config schema | `scripts/config/schema.ts` | TypeBox type definitions |
+| Config validation | `scripts/config/validate.ts` | Schema validation + typed errors |
+| Trace normalization | `scripts/normalize/platforms/*.ts` | Platform JSON → canonical shape |
+| Setup detection | `scripts/setup/detect.ts` | File reads + state checks |
+| Stale-target hash compare | `scripts/stale-detector.ts` | Pure hash compare |
+| HTML report render | `scripts/report/render.ts` | Template + data → HTML |
+| [INTERNAL] Host probe | `scripts/self-diagnostics/probe.ts` | Env + fs probing |
+| [INTERNAL] Self-dispatch | `scripts/self-diagnostics/dispatch.ts` | Descriptor file write |
+
+---
+
+## Type B — Agent Operations (12 items)
+
+| Op | Agent action |
+|----|-------------|
+| Sub-agent dispatch | `Agent({subagent_type: 'diagnostics-analyzer', run_in_background: true})` |
+| Trace fetch from source | `Bash(<cli> traces list ...)` per per-platform reference doc |
+| Score-scale probe | `Bash(<cli> scores list --json)` + LLM classification |
+| NL → TraceFilter translation | LLM reasoning over operator query |
+| Cross-analyzer dedup | LLM reasoning over collected findings |
+| RCA (3-dim WHAT/WHY/WHERE) | LLM reasoning per finding |
+| Recursive whys | LLM reasoning (PR-020) |
+| Remedy ranking | LLM judgment (cost × correctness) |
+| HITL approval gate | `AskUserQuestion` / chat-fallback |
+| BG-worktree apply | `Bash(git worktree + commit + push + gh pr create)` |
+| REST apply | `Bash(curl GET + PUT)` with idempotency-key |
+| CLI install check | `Bash(which <cli>)` + prompt (PR-021) |
+
+---
+
+## Type C — Hybrid (orchestrator invoking scripts)
+
+| Op | Pattern |
+|----|---------|
+| Orchestrator invoking tier0 | Agent calls `Bash(scripts/cli/run.sh scripts/tier0-scan.ts ...)` → reads structured JSON output |
+| Orchestrator invoking slicer | Agent calls `Bash(scripts/cli/run.sh scripts/slicer.ts ...)` → reads slice plan JSON |
+| Apply-worker invoking stale-detector | Agent calls `Bash(scripts/cli/run.sh scripts/stale-detector.ts ...)` → reads freshness result |
+| Orchestrator invoking report render | Agent calls `Bash(scripts/cli/run.sh scripts/report/render.ts ...)` → reads report.html path |
+| Init invoking setup/detect | Agent calls `Bash(scripts/cli/run.sh scripts/setup/detect.ts)` → routes based on SetupState |

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/overview.md

@@ -0,0 +1,167 @@
+# mutagent-diagnostics — Overview
+
+> **PRD-SO-01** · First reading for new users. This is the primer; `SKILL.md` is the
+> manifest. Load `references/reference.md` next for the full architecture + dependency graph.
+
+---
+
+## What this skill does
+
+`mutagent-diagnostics` is a diagnostics-on-tap skill for AI agents. Given access to your
+agent traces (from Langfuse, OpenTelemetry, local JSONL, Claude Code transcripts, or Codex
+transcripts), the skill runs a full RCA cycle and produces a gold-standard HTML report
+covering every detected failure with ranked remedies, a two-rationale remedy card, a feedback
+block grounded in operator chat and trace scores, and a copy-back markdown bundle you can
+hand straight to an apply agent.
+
+The skill operates as an inline orchestrator running inside your coding-agent session. It
+dispatches up to five parallel Analyzer sub-agents, aggregates their structured findings,
+enriches them deterministically, and renders the result. No external server, no subscription,
+no separate process — the skill IS the orchestrator.
+
+On first invocation the skill detects whether a config exists. If not, it walks you through
+an eight-phase onboarding: source platform, target platform, ASK tool, schedule mode, and
+trigger rules. Subsequent invocations go straight to the diagnostic pipeline.
+
+---
+
+## When to use it
+
+| Trigger | Example | Outcome |
+|---------|---------|---------|
+| A user reported an agent failure | "my sample-email-agent returned wrong data" | Full RCA with WHAT/WHY/WHERE taxonomy, ranked remedies |
+| Trace score dropped | Langfuse score fell below 0.6 | Cost-scoped analysis; coverage-proofed findings |
+| You shipped a change and want a pre-release check | Before merging a prompt update | Structured findings vs declared success criteria (contract mode) |
+| You suspect methodology drift in your diagnostics skill | Skill maintainer running self-diag | `[INTERNAL]` META-audience report; `--self-diag` flag |
+| You want a neutral survey of the last 24h | No specific complaint | Window-based slicer; exploratory open-ended report |
+
+**When NOT to use it:**
+- Real-time alerting — the skill produces a point-in-time report, not a streaming monitor.
+- Replacing your observability platform — the skill reads FROM your platform, not instead of it.
+- Scheduling automated runs — v0.1 is on-demand only; see `references/workflows/schedule-prep.md`.
+
+---
+
+## Quick-start (5-minute onboarding)
+
+### Step 1 — Install (one-time)
+
+```bash
+pnpx @mutagent/diagnostics init
+```
+
+This detects your runtime, copies required templates, and launches the onboarding wizard.
+
+### Step 2 — Run the wizard
+
+The onboarding wizard asks four questions:
+
+1. **Source platform** — where your traces live (Langfuse / OTel / local JSONL / Claude Code / Codex).
+2. **Target platform** — where your agent definitions live (e.g., `.claude/agents/` for Claude Code agents; `cloud-rest` for remote agents; `report-only` to skip apply entirely).
+3. **ASK tool** — auto-detected from your runtime.
+4. **Trigger rules** — which traces qualify for diagnosis (e.g., `score_below: 0.6`).
+
+Config is saved to `<project>/.mutagent/config.yaml`. Secrets (API keys) live in
+`<project>/.mutagentrc` (gitignored).
+
+### Step 3 — Diagnose
+
+In your coding-agent chat:
+
+```
+/mutagent-diagnostics
+```
+
+Or with a brief:
+
+```
+/mutagent-diagnostics "diagnose sample-email-agent focus on cost loops last 24h"
+```
+
+The brief is parsed into `{ agent, timeWindow, focus, residual }` by
+`scripts/invocation/parse-brief.ts`. A `focus` directive activates Guided mode (the Guided
+tab replaces Overview). No focus means a neutral survey.
+
+### Step 4 — Review the report
+
+The skill opens an HTML report in your browser. The report has four tab types:
+
+- **Methodology [INTERNAL]** — how the diagnosis was run (orchestrator trace, decisions log).
+- **Overview** — entity card, 6-tile big-stat row, 24h latency heatmap, findings table.
+- **F-NNN tabs** — one per finding: severity badge, taxonomy chips, problem, evidence,
+  why-chain, assumptions, coverage proof, ranked remedies.
+- **Decisions** — live-preview markdown bundle; check remedies, add notes, click Copy.
+
+### Step 5 — Apply
+
+Paste the copied markdown bundle into your coding-agent chat. The apply worker spawns a
+background agent on an isolated worktree, makes the changes, and opens a PR.
+
+---
+
+## Anatomy of a diagnostic report
+
+For the full panel-by-panel anatomy — every block in the issue card, every element in the
+remedy card, the live-preview mechanics — see:
+
+```
+references/workflows/rendering-anatomy.md
+```
+
+Key elements per finding panel:
+
+| Block | Location | Notes |
+|-------|----------|-------|
+| Severity badge | Top-left | CRIT / HIGH / MED / INFO |
+| Taxonomy chips | Below title | WHAT · WHY · WHERE · APPLY · AUDIENCE |
+| Feedback block | Between Problem and Evidence | Color-coded by source (chat=cyan, score=yellow, external=purple). Only appears when `feedbackSources[]` is populated. |
+| Why-chain | Below evidence | Causal steps; deepest marked `isOrigin: true` |
+| Assumptions | Below why-chain | Verified / unverified / hypothesis-pending pills |
+| Coverage proof | Below assumptions | 4-dim widget (latency, score, temporal, tool-trajectory); low confidence shows yellow banner |
+| Remedy card | Per remedy | Two-rationale blocks (purple Why + cyan WhyWorks); diff grid; apply plan + instructions; notes textarea |
+
+---
+
+## What the skill does NOT do
+
+- **Does not monitor continuously.** It runs on-demand or on a schedule you configure.
+- **Does not auto-apply without approval.** Every apply goes through a HITL copy-back gate.
+- **Does not hallucinate entity data.** The entity card is populated deterministically from
+  trace metadata and your config — no LLM is involved in entity extraction.
+- **Does not reveal PII.** The system prompt field in the entity card is always collapsed
+  (explicit click to view) regardless of size.
+- **Does not run self-diagnostics automatically.** `self_diagnostics.enabled` defaults to
+  false; enabling it is a skill-maintainer opt-in.
+- **Does not cross-reference other skills.** Each skill is a sealed unit.
+
+---
+
+## Glossary
+
+| Term | Definition |
+|------|------------|
+| **Tier-0** | Static pattern scan (`scripts/tier0-scan.ts`) — runs BEFORE any LLM call to bound token cost. Measures cheap signals (latency distribution, error counts, score thresholds). |
+| **RCA** | Root Cause Analysis — the 3-dimensional `(WHAT, WHY, WHERE)` failure taxonomy produced by the Analyzer agents. See `references/workflows/rca.md`. |
+| **EntityContext** | Auto-extracted agent descriptor: name, model, system prompt, tool inventory with per-tool stats, input sample. Populated deterministically by the source-platform normalizer — no LLM. |
+| **applyTarget** | The symbolic reference to the agent definition the remedy should be applied to (e.g., `.claude/agents/search-agent.md` for a local Claude agent). Declared by the Analyzer; rendered in the remedy meta strip. |
+| **rationale** | The comparative remedy rationale block — WHY this remedy over alternatives (purple). Always visible, never collapsible. |
+| **whyWorks** | The causal mechanism block — HOW the fix closes the failure (cyan). Always visible, never collapsible. |
+| **coverageProof** | 4-dimensional sampling audit: for each of latency, score, temporal, and tool-trajectory, what fraction of the population buckets did the sample cover? Confidence mapped to high/med/low via 90/70 thresholds. |
+| **Wave-6 methodology** | The diagnostic methodology layer (R2.1–R2.6 + D1/D2): mandatory LLM deep-read gate, awareness mini-sample, representative 4-bucket sampler, class-memory library, blind-spots taxonomy, and coverage proof. |
+| **report-only** | A `target.platform` value that skips the apply gate entirely. Useful for read-only environments or when you want a report without committing to any changes. |
+| **feedbackSources** | Structured list of operator feedback linked to a finding: chat messages (`chat`), Langfuse trace scores (`trace-score`), or external feedback platform entries (`external`). |
+
+---
+
+## Further reading (progressive disclosure)
+
+| Doc | When to read |
+|-----|-------------|
+| `references/reference.md` | Full architecture DAG + complete TOC |
+| `references/workflows/orchestrator-protocol.md` | The step-by-step diagnostic run procedure |
+| `references/workflows/onboarding.md` | Onboarding phase-by-phase detail |
+| `references/workflows/rca.md` | RCA taxonomy + finding shape |
+| `references/workflows/rendering-anatomy.md` | Canonical per-finding + per-remedy anatomy |
+| `references/principles.md` | 53 design principles (PR-001..PR-053) — the audit surface |
+| `references/config.md` | Full config schema with doc strings and examples |
+| `SKILL.md` | The manifest: §0 setup detection, §3 architecture, §4 bill of materials |