selftune 0.2.0 → 0.2.2

package/skill/Workflows/Baseline.md

@@ -4,10 +4,18 @@ Measure whether a skill adds value over a no-skill baseline. Runs trigger
 checks with and without the skill description to compute lift — the
 improvement in pass rate that the skill provides.
 
+## When to Invoke
+
+Invoke this workflow when the user requests any of the following:
+- Measuring whether a skill adds value or is worth keeping
+- Comparing skill performance against a no-skill baseline
+- Deciding whether to evolve or rework a skill
+- Any request containing "baseline", "does this skill help", or "skill value"
+
 ## Default Command
 
 ```bash
-selftune baseline --skill <name> --skill-path <path> [options]
+selftune grade baseline --skill <name> --skill-path <path> [options]
 ```
 
 ## Options
@@ -59,27 +67,34 @@ skipped — the skill needs fundamental rework, not description tweaks.
 
 ### 0. Pre-Flight Configuration
 
-Before running baseline measurement, present configuration options to the user.
-If the user says "use defaults" or similar, skip to step 1 with recommended defaults.
+Before running baseline measurement, present numbered configuration options to the user inline in your response, then wait for the user's answer before proceeding.
 
-Present these options:
+If the user responds with "use defaults", "just do it", or similar shorthand, skip to step 1 using the recommended defaults.
 
-```
-selftune baseline — Pre-Flight Configuration
+Present the following options inline in your response:
 
-1. Eval Set Source
-   a) Auto-generate from logs (recommended if logs exist)
-   b) Use existing eval set file — provide path
-   c) Generate synthetic evals first (for new skills with no data)
+1. **Eval Set Source**
+   - a) Auto-generate from logs (recommended if logs exist)
+   - b) Use existing eval set file — provide path
+   - c) Generate synthetic evals first (for new skills with no data)
 
-2. Agent CLI
-   a) Auto-detect (recommended)
-   b) Specify: claude / codex / opencode
+2. **Agent CLI**
+   - a) Auto-detect (recommended)
+   - b) Specify: claude / codex / opencode
 
-→ Reply with your choices or "use defaults" for recommended settings.
-```
+Ask: "Reply with your choices or 'use defaults' for recommended settings."
+
+After the user responds, parse their selections and map each choice to the corresponding CLI flags:
 
-After the user responds, show a confirmation summary:
+| Selection | CLI Flag |
+|-----------|----------|
+| 1a (auto-generate) | _(no flag, default)_ |
+| 1b (existing eval set) | `--eval-set <path>` |
+| 1c (synthetic first) | Run Evals workflow with `--synthetic` first, then use output |
+| 2a (auto-detect) | _(no flag, default)_ |
+| 2b (specify agent) | `--agent <name>` |
+
+Show a confirmation summary to the user:
 
 ```
 Configuration Summary:
@@ -89,12 +104,16 @@ Configuration Summary:
 Proceeding...
 ```
 
+Build the CLI command string with all selected flags and continue to step 1.
+
 ### 1. Run Baseline Measurement
 
 ```bash
-selftune baseline --skill Research --skill-path ~/.claude/skills/Research/SKILL.md
+selftune grade baseline --skill Research --skill-path ~/.claude/skills/Research/SKILL.md
 ```
 
+Parse the JSON output and extract `lift` and `adds_value` fields.
+
 ### 2. Interpret Results
 
 | Lift | Interpretation | Action |
@@ -104,6 +123,8 @@ selftune baseline --skill Research --skill-path ~/.claude/skills/Research/SKILL.
 | < 0.05 | Minimal value | Skill may need rework, not just evolution |
 | < 0 | Negative value | Skill is hurting — investigate or disable |
 
+Report the interpretation to the user based on the lift value.
+
 ### 3. Use as Evolution Gate
 
 Add `--with-baseline` to evolve commands to prevent wasting evolution
@@ -111,11 +132,13 @@ cycles on skills that don't add value.
 
 ## Common Patterns
 
-**"Does the Research skill add value?"**
-> `selftune baseline --skill Research --skill-path ~/.claude/skills/Research/SKILL.md`
+**User asks whether a skill adds value (e.g., "does the Research skill help?"):**
+Run `selftune grade baseline --skill Research --skill-path ~/.claude/skills/Research/SKILL.md`.
+Parse the JSON output and report the lift value with interpretation.
 
-**"Only evolve if the skill is actually useful"**
-> `selftune evolve --skill Research --skill-path /path/SKILL.md --with-baseline`
+**User wants to gate evolution on baseline value:**
+Run `selftune evolve --skill Research --skill-path /path/SKILL.md --with-baseline`.
+This measures baseline lift before deploying and skips evolution if lift is below 5%.
 
-**"Check baseline with a custom eval set"**
-> `selftune baseline --skill pptx --skill-path /path/SKILL.md --eval-set evals-pptx.json`
+**User wants to test with a custom eval set:**
+Run `selftune grade baseline --skill pptx --skill-path /path/SKILL.md --eval-set evals-pptx.json`.

package/skill/Workflows/Composability.md

@@ -7,7 +7,7 @@ co-occurring than when used alone.
 ## Default Command
 
 ```bash
-selftune composability --skill <name> [options]
+selftune eval composability --skill <name> [options]
 ```
 
 ## Options
@@ -65,7 +65,7 @@ The analyzer is a pure function that computes conflict scores from telemetry:
 ### 1. Run Analysis
 
 ```bash
-selftune composability --skill Research
+selftune eval composability --skill Research
 ```
 
 ### 2. Interpret Results
@@ -79,19 +79,26 @@ selftune composability --skill Research
 
 ### 3. Address Conflicts
 
-For conflict candidates:
+When conflict candidates are identified, present them to the user with recommended actions:
 - Check for trigger keyword overlap between the skills
 - Check if one skill's workflow interferes with the other's
 - Consider evolving descriptions to reduce false triggers
 - Use the `pattern-analyst` agent for deeper cross-skill analysis
 
+## Subagent Escalation
+
+For deep cross-skill analysis beyond what the composability command provides,
+spawn the `pattern-analyst` agent as a subagent. This is useful when conflict
+scores are high (> 0.3) and you need a full resolution plan with trigger
+ownership recommendations.
+
 ## Common Patterns
 
 **"Are there conflicts between my skills?"**
-> `selftune composability --skill Research`
+> `selftune eval composability --skill Research`
 
 **"Check composability for recent sessions only"**
-> `selftune composability --skill pptx --window 7`
+> `selftune eval composability --skill pptx --window 7`
 
 **"Which skills conflict with Research?"**
 > Run composability and check the `conflict_candidates` array.

package/skill/Workflows/Contribute.md

@@ -6,9 +6,9 @@ private data.
 
 ## When to Use
 
-- Want to help improve selftune's skill routing
-- Sharing anonymized usage patterns with the community
-- Contributing eval data for skill evolution
+- The user asks to contribute data, share usage patterns, or help improve selftune
+- The user wants to export anonymized skill observability data
+- The agent needs to submit eval data for community skill evolution
 
 ## Default Command
 
@@ -71,21 +71,24 @@ No raw transcripts, file contents, or identifiable information is included.
 
 ## Steps
 
-1. Run `selftune contribute --preview --skill selftune` to see what would be shared
-2. Review the sanitized output
+1. Run `selftune contribute --preview --skill selftune` to preview the contribution bundle
+2. Parse the output and report the sanitized data summary to the user for review
 3. Run `selftune contribute --skill selftune` to write the bundle
-4. Optionally: `selftune contribute --skill selftune --submit` to create GitHub issue
+4. If the user wants to submit directly, run `selftune contribute --skill selftune --submit`
 
 ## Common Patterns
 
-**"Preview what I'd share"**
-> `selftune contribute --preview`
+**User wants to see what would be shared**
+> Run `selftune contribute --preview`. Parse the output and report the
+> sanitized data summary to the user before proceeding.
 
-**"Use aggressive sanitization"**
-> `selftune contribute --sanitize aggressive`
+**User requests stronger anonymization**
+> Run `selftune contribute --sanitize aggressive`. This replaces identifiers,
+> quoted strings, and module paths in addition to standard PII scrubbing.
 
-**"Submit directly to GitHub"**
-> `selftune contribute --submit`
+**User wants to submit directly**
+> Run `selftune contribute --submit`. This creates a GitHub Issue via `gh`
+> CLI with the bundle inlined or uploaded as a gist.
 
-**"Only contribute recent data"**
-> `selftune contribute --since 2026-02-01`
+**User wants to limit to recent data**
+> Run `selftune contribute --since <date>` with the user's specified date.

package/skill/Workflows/Cron.md

@@ -1,40 +1,37 @@
 # selftune Cron Workflow
 
-Manage OpenClaw cron jobs that run the selftune pipeline on a schedule.
-Enables fully autonomous skill evolution — skills improve while you sleep.
+Set up scheduled automation for the selftune pipeline. Auto-detects the
+platform (system cron, macOS launchd, Linux systemd) or can target
+OpenClaw-specific cron integration.
 
 ## When to Use
 
-- Setting up selftune automation for the first time on OpenClaw
+- Setting up selftune automation for the first time
 - Checking which cron jobs are registered
 - Removing selftune cron jobs (cleanup or reconfiguration)
 - Enabling the autonomous observe-grade-evolve-deploy loop
 
-## Prerequisites
+## Commands
 
-OpenClaw must be installed and in your PATH. The setup command will check
-for this and exit with instructions if OpenClaw is not found.
-
-```bash
-which openclaw    # Must resolve
-```
+### `selftune cron setup`
 
-## Default Command
+Auto-detect the current platform and install scheduled jobs.
 
-```bash
-selftune cron setup
-```
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--platform <name>` | Force a specific platform (`openclaw`, `cron`, `launchd`, `systemd`) | Auto-detect |
+| `--dry-run` | Preview without installing | Off |
+| `--tz <timezone>` | IANA timezone for job schedules (OpenClaw only) | Flag > `TZ` env > system timezone |
 
-## Subcommands
+Platform auto-detection: macOS → launchd, Linux → systemd, other → cron.
 
-### `selftune cron setup`
+### `selftune cron setup --platform openclaw`
 
-Register the default selftune cron jobs with OpenClaw.
+Register selftune cron jobs with OpenClaw. Requires OpenClaw installed and on PATH.
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--dry-run` | Preview commands without registering jobs | Off |
-| `--tz <timezone>` | IANA timezone for job schedules | Flag > `TZ` env > system timezone |
+```bash
+which openclaw    # Must resolve
+```
 
 ### `selftune cron list`
 
@@ -50,106 +47,86 @@ Remove all selftune cron jobs from OpenClaw.
 |------|-------------|---------|
 | `--dry-run` | Preview which jobs would be removed without deleting | Off |
 
+## Aliases
+
+`selftune schedule` is an alias for `selftune cron`. Existing `selftune schedule`
+invocations with flags (e.g. `selftune schedule --platform launchd`) continue to work.
+
 ## Default Job Schedule
 
-Setup registers these four jobs:
+Setup registers these jobs:
 
 | Name | Cron Expression | Schedule | Description |
 |------|----------------|----------|-------------|
-| `selftune-ingest` | `*/30 * * * *` | Every 30 minutes | Ingest new sessions from OpenClaw transcripts |
+| `selftune-sync` | `*/30 * * * *` | Every 30 minutes | Sync source-truth telemetry |
 | `selftune-status` | `0 8 * * *` | Daily at 8am | Health check — report skills with pass rate below 80% |
-| `selftune-evolve` | `0 3 * * 0` | Weekly at 3am Sunday | Full evolution pipeline for undertriggering skills |
-| `selftune-watch` | `0 */6 * * *` | Every 6 hours | Monitor recently evolved skills for regressions |
+| `selftune-orchestrate` | `0 */6 * * *` | Every 6 hours | Full autonomous loop: sync → candidate selection → evolve → watch |
 
 All jobs run in **isolated session** mode — each execution gets a clean
 session with no context accumulation from previous runs.
 
 ## Output
 
-- **setup:** Registers jobs via `openclaw cron add` and confirms each registration
+- **setup:** Installs platform-appropriate schedule artifacts and activates them
+- **setup --platform openclaw:** Registers jobs via `openclaw cron add` and confirms each
 - **list:** Prints a formatted table of registered selftune cron jobs (name, schedule, description)
 - **remove:** Deletes each selftune cron job via `openclaw cron remove` and confirms
 
-Jobs persist at `~/.openclaw/cron/jobs.json` and survive OpenClaw restarts.
-
 ## Steps
 
-1. Run `selftune cron setup --dry-run` to preview what would be registered
-2. Run `selftune cron setup` to register the default jobs
+1. Run `selftune cron setup --dry-run` to preview what would be installed
+2. Run `selftune cron setup` to install scheduled jobs for your platform
+3. Verify with `selftune status` after the first scheduled run fires
+
+For OpenClaw specifically:
+1. Run `selftune cron setup --platform openclaw --dry-run` to preview
+2. Run `selftune cron setup --platform openclaw` to register jobs
 3. Run `selftune cron list` to verify jobs are registered
-4. Wait for the first cron cycle to fire (ingest runs every 30 minutes)
-5. Check results with `selftune status` after the first daily health check
 
 ## The Autonomous Evolution Loop
 
-When cron jobs are active, selftune operates as a self-correcting system:
+When scheduled jobs are active, selftune operates as a self-correcting system.
+The OS scheduler calls the CLI binary directly — no agent session is needed,
+no token cost for routine runs.
 
-```
-Cron fires (isolated session)
+```text
+OS scheduler fires (cron/launchd/systemd)
     |
     v
-Agent runs selftune pipeline (ingest -> status -> evolve -> watch)
+selftune orchestrate --max-skills 3   (CLI runs directly, no agent)
     |
     v
-Improved SKILL.md written to disk
-    |
-    v
-OpenClaw file watcher detects change (250ms debounce)
+sync → candidate selection → evolve → validate → deploy → watch
     |
     v
-Skill snapshot version bumped — next agent turn uses updated description
+Improved SKILL.md written to disk
     |
     v
-Better triggering in real-time, no restart needed
+Next interactive agent session uses updated description
 ```
 
-The four jobs form a continuous loop:
-- **ingest** captures raw session data every 30 minutes
-- **status** identifies undertriggering skills daily
-- **evolve** proposes and deploys improvements weekly
-- **watch** monitors for regressions every 6 hours and auto-rolls back if needed
-
-Skills improve and take effect within seconds of the cron job completing.
-No deployment step, no restart, no manual intervention.
+This is distinct from interactive mode where the user says "improve my skills"
+and the agent runs orchestrate. Automated mode is for routine maintenance;
+interactive mode is for user-directed improvements.
 
 ## Safety Controls
 
 | Control | How It Works |
 |---------|-------------|
-| Dry-run first | `selftune cron setup --dry-run` previews commands before registering |
+| Dry-run first | `selftune cron setup --dry-run` previews commands before installing |
 | Regression threshold | Evolution only deploys if improvement exceeds 5% on existing triggers |
 | Auto-rollback | `selftune watch` automatically rolls back if pass rate drops below baseline minus threshold |
 | Audit trail | Every evolution recorded in `evolution_audit_log.jsonl` with full history |
 | SKILL.md backup | `.bak` file created before every deploy — primary rollback path exists via .bak; fallback depends on audit metadata integrity |
-| Isolated sessions | Each cron run gets a clean session (no context pollution between runs) |
-| Human override | `selftune rollback --skill <name> --skill-path <path>` available anytime to manually revert |
+| Human override | `selftune evolve rollback --skill <name> --skill-path <path>` available anytime to manually revert |
 | Pin descriptions | Config flag to freeze specific skills and prevent evolution on sensitive skills |
 
 ## Common Patterns
 
-**"Set up autonomous skill evolution"**
-> Run `selftune cron setup`. The four default jobs handle ingestion,
-> health checks, evolution, and regression monitoring.
-
-**"Preview before registering"**
-> Run `selftune cron setup --dry-run` to see exactly what commands
-> would be executed without registering anything.
-
-**"Use a specific timezone"**
-> Run `selftune cron setup --tz America/New_York`. Without the flag,
-> timezone resolution is: `--tz` flag > `TZ` environment variable > system timezone.
-
-**"What jobs are registered?"**
-> Run `selftune cron list`. Shows a table of all selftune cron jobs
-> with their schedules and descriptions.
-
-**"Remove all cron automation"**
-> Run `selftune cron remove`. Preview first with `selftune cron remove --dry-run`.
-
-**"A skill regressed after cron evolution"**
-> The watch job should catch this automatically. If not, run
-> `selftune rollback --skill <name>` manually. See `Workflows/Rollback.md`.
-
-**"How do I know the cron loop is working?"**
-> Run `selftune status` after the first daily health check fires (8am).
-> Check `evolution_audit_log.jsonl` for entries with recent timestamps.
+- **User wants autonomous skill evolution** -- Run `selftune cron setup`. Auto-detects the platform and installs appropriate scheduled jobs.
+- **User specifies OpenClaw** -- Run `selftune cron setup --platform openclaw`.
+- **User wants to preview before installing** -- Run `selftune cron setup --dry-run` to show exactly what would be installed without changing anything.
+- **User needs a specific timezone (OpenClaw)** -- Run `selftune cron setup --platform openclaw --tz America/New_York`.
+- **User asks what jobs are registered** -- Run `selftune cron list`. Shows a table of all selftune cron jobs with their schedules and descriptions.
+- **User wants to remove cron automation** -- Run `selftune cron remove`. Preview first with `selftune cron remove --dry-run`.
+- **Skill regressed after cron evolution** -- The watch job should catch this automatically. If not, run `selftune evolve rollback --skill <name> --skill-path <path>` manually. See `Workflows/Rollback.md`.

package/skill/Workflows/Dashboard.md

@@ -2,7 +2,7 @@
 
 Visual dashboard for selftune telemetry, skill performance, evolution
 audit, and monitoring data. Supports static HTML export, file output,
-and a live server with SSE auto-refresh and action buttons.
+and a live server with polling-based auto-refresh and action buttons.
 
 ## Default Command
 
@@ -53,9 +53,10 @@ selftune dashboard --out /tmp/report.html
 
 ### Live Server
 
-Starts a Bun HTTP server with real-time data updates via Server-Sent
-Events (SSE). The dashboard auto-refreshes every 5 seconds and provides
-action buttons to trigger selftune commands.
+Starts a Bun HTTP server with a React SPA dashboard. The SPA uses
+TanStack Query polling to auto-refresh data (overview every 15s,
+orchestrate runs every 30s, doctor every 30s) and provides action
+buttons to trigger selftune commands.
 
 ```bash
 selftune dashboard --serve
@@ -73,19 +74,28 @@ override.
 
 | Method | Path | Description |
 |--------|------|-------------|
-| `GET` | `/` | Serve dashboard HTML with embedded data and live mode flag |
-| `GET` | `/api/data` | JSON endpoint returning current telemetry data |
-| `GET` | `/api/events` | SSE stream sending data updates every 5 seconds |
+| `GET` | `/` | Serve dashboard SPA shell |
+| `GET` | `/api/v2/overview` | SQLite-backed overview payload |
+| `GET` | `/api/v2/skills/:name` | SQLite-backed per-skill report |
+| `GET` | `/api/v2/orchestrate-runs` | Recent orchestrate run reports |
+| `GET` | `/api/v2/doctor` | System health diagnostics (config, logs, hooks, evolution) |
+| `GET` | `/api/health` | Dashboard server health probe |
 | `POST` | `/api/actions/watch` | Trigger `selftune watch` for a skill |
 | `POST` | `/api/actions/evolve` | Trigger `selftune evolve` for a skill |
-| `POST` | `/api/actions/rollback` | Trigger `selftune rollback` for a skill |
+| `POST` | `/api/actions/rollback` | Trigger `selftune evolve rollback` for a skill |
 
-### SSE Auto-Refresh
+### Auto-Refresh
 
-The `/api/events` endpoint opens an SSE connection that pushes fresh
-data every 5 seconds. The dashboard client listens for `data` events
-and re-renders automatically. When `window.__SELFTUNE_LIVE__` is set
-(injected by the live server), the dashboard enables SSE polling.
+The dashboard SPA uses TanStack Query with `refetchInterval` to poll
+the v2 API endpoints automatically:
+
+- `/api/v2/overview` — every 15 seconds
+- `/api/v2/orchestrate-runs` — every 30 seconds
+- `/api/v2/doctor` — every 30 seconds
+- `/api/v2/skills/:name` — every 30 seconds (when viewing a skill)
+
+Data also refreshes on window focus. No SSE or websocket connection
+is required.
 
 ### Action Endpoints
 
@@ -128,8 +138,8 @@ On failure, `success` is `false` and `error` contains the error message.
 The live server auto-opens the dashboard URL in the default browser on
 macOS (`open`) and Linux (`xdg-open`).
 
-Graceful shutdown on `SIGINT` (Ctrl+C) and `SIGTERM`: closes all SSE
-client connections and stops the server.
+Graceful shutdown on `SIGINT` (Ctrl+C) and `SIGTERM`: closes the SQLite
+database and stops the server.
 
 ## Data Contents
 
@@ -173,31 +183,32 @@ selftune dashboard --serve
 ### 3. Interact with Dashboard
 
 - **Static mode**: View the snapshot. Re-run to refresh.
-- **Live mode**: Data refreshes automatically every 5 seconds. Use
-  action buttons to trigger watch, evolve, or rollback directly from
+- **Live mode**: Data refreshes automatically via polling (15-30s intervals).
+  Use action buttons to trigger watch, evolve, or rollback directly from
   the dashboard.
 
 ## Common Patterns
 
-**"Show me the dashboard"**
-> Run `selftune dashboard`. Opens a browser with current data.
+**User wants to see skill performance visually**
+> Run `selftune dashboard`. This opens a browser with a point-in-time snapshot.
+> Report to the user that the dashboard is open.
 
-**"I want live updates"**
-> Run `selftune dashboard --serve`. The SSE stream refreshes every 5
-> seconds without manual intervention.
+**User wants live monitoring**
+> Run `selftune dashboard --serve`. Inform the user that data refreshes
+> automatically every 15-30 seconds via polling.
 
-**"Export a report"**
-> Use `selftune dashboard --out report.html` to save a self-contained
-> HTML file. Share it -- no server needed, all data is embedded.
+**User wants a shareable report**
+> Run `selftune dashboard --out report.html`. Report the file path to the
+> user. The HTML file is self-contained with all data embedded.
 
-**"The dashboard shows no data"**
-> No log files found. Run some sessions first so hooks generate
-> telemetry. Check `selftune doctor` to verify hooks are installed.
+**Dashboard shows no data**
+> Run `selftune doctor` to verify hooks are installed. If hooks are missing,
+> route to the Initialize workflow. If hooks are present but no sessions
+> have run, inform the user that sessions must generate telemetry first.
 
-**"Use a different port"**
-> `selftune dashboard --serve --port 8080`. Port must be 1-65535.
+**User wants a different port**
+> Run `selftune dashboard --serve --port <port>`. Port must be 1-65535.
 
-**"Trigger actions from the dashboard"**
-> In live server mode, the dashboard provides buttons to trigger watch,
-> evolve, and rollback for each skill. These call the action endpoints
-> which spawn selftune subprocesses.
+**User wants to trigger actions from the dashboard**
+> Run `selftune dashboard --serve` for live mode. The dashboard provides
+> action buttons for watch, evolve, and rollback per skill via POST endpoints.

package/skill/Workflows/Doctor.md

@@ -105,8 +105,8 @@ Doctor validates these areas:
 
 | Check | What it validates |
 |-------|-------------------|
-| Agent directory exists | `.claude/agents/` directory is present |
-| Agent files present | Expected agent files exist: `diagnosis-analyst.md`, `pattern-analyst.md`, `evolution-reviewer.md`, `integration-guide.md` |
+| Optional agent directory exists | If `.claude/agents/` is present, it is readable |
+| Optional agent files present | If the repo bundles helper agents, the expected files are present |
 
 ### Dashboard Checks (optional)
 
@@ -147,28 +147,41 @@ For each failed check, take the appropriate action:
 | Evolution guard missing | Add `hooks/evolution-guard.ts` to `PreToolUse` in settings. |
 | Memory directory missing | Run `mkdir -p ~/.selftune/memory`. |
 | Memory files invalid | Delete and let the memory writer recreate them on next evolve/watch. |
-| Activation rules missing | Copy `templates/activation-rules-default.json` to `~/.selftune/activation-rules.json`. |
+| Activation rules missing | Copy `assets/activation-rules-default.json` to `~/.selftune/activation-rules.json`. |
 | Activation rules invalid | Validate JSON syntax. Re-copy from template if corrupted. |
-| Agent files missing | Copy agents from the selftune repo `.claude/agents/` directory. |
+| Agent files missing | If your repo uses optional helper agents, restore them in `.claude/agents/`. Otherwise ignore this advisory. |
 | Audit log invalid | Remove corrupted entries. Future operations will append clean entries. |
 
 ### 4. Re-run Doctor
 
 After fixes, run doctor again to verify all checks pass.
 
-## Common Patterns
-
-**"Something seems broken"**
-> Run doctor first. Report any failing checks with their detail messages.
+## Subagent Escalation
 
-**"Are my hooks working?"**
-> Doctor checks hook installation. If hooks pass but no data appears,
-> verify the hook script paths point to actual files.
+If doctor reveals persistent issues with a specific skill — especially
+recurring failures that basic fixes do not resolve — spawn the
+`diagnosis-analyst` agent as a subagent for root cause analysis.
 
-**"No telemetry available"**
-> Doctor will report missing log files. Install hooks using the
-> `settings_snippet.json` in the skill directory, then run a session.
+## Common Patterns
 
-**"Check selftune health"**
-> Run doctor and report the summary. A clean bill of health means
-> all checks pass and selftune is ready to grade/evolve/watch.
+**User reports something seems broken**
+> Run `selftune doctor`. Parse the JSON output for failed checks. Report
+> each failure's `name` and `detail` to the user with the recommended fix.
+
+**User asks if hooks are working**
+> Run `selftune doctor`. Parse `.checks[]` for hook-related entries. If
+> hooks pass but no data appears, verify hook script paths in
+> `~/.claude/settings.json` point to actual files.
+
+**No telemetry data available**
+> Run `selftune doctor`. Route fixes by platform:
+> - **Claude Code** — route to the Initialize workflow to install hooks
+> - **Codex** — run `selftune ingest codex` or `selftune ingest wrap-codex`
+> - **OpenCode** — run `selftune ingest opencode`
+> - **OpenClaw** — run `selftune ingest openclaw`
+> At least one session must complete after setup to generate telemetry.
+
+**User asks to check selftune health**
+> Run `selftune doctor`. Parse `.healthy` and `.summary`. If `healthy: true`,
+> report that selftune is fully operational. If false, report failed checks
+> and recommended fixes.