@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/claude/dogfood/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: dogfood
+description: "Review failed Exarchos MCP tool calls from the current session, diagnose root causes, and categorize into code bug, documentation issue, or user error. Use when the user says 'dogfood', 'review failures', 'what went wrong', 'triage errors', or runs /dogfood. Scopes exclusively to Exarchos tools (exarchos_workflow, exarchos_event, exarchos_orchestrate, exarchos_view, exarchos_sync). Do NOT use for debugging application code or non-Exarchos tool failures."
+metadata:
+  author: exarchos
+  version: 2.0.0
+  mcp-server: exarchos
+  category: utility
+---
+
+# Dogfood Skill
+
+## Overview
+
+Retrospective analysis of Exarchos MCP tool usage. Uses the MCP server's own self-service capabilities as the primary diagnostic instrument — describe APIs, views, playbooks, and runbooks turned inward to diagnose failures.
+
+Three distinct failure modes require different fixes — code changes, documentation updates, or skill instruction improvements. Mixing them wastes effort.
+
+### Platform-Agnosticity
+
+Per `docs/designs/2026-03-09-platform-agnosticity.md`: the MCP server is the self-sufficient, platform-agnostic core. The debug trace relies entirely on MCP tools — not conversation introspection — so it works for any MCP client. Conversation scanning is supplementary.
+
+**Diagnostic self-service tools:** `describe(topology)` for HSM verification, `describe(playbook)` for adherence checks, `describe(eventTypes, emissionGuide)` for event schema/catalog comparison, `describe(actions)` for schema/gate metadata, `runbook(phase)` for step conformance, `pipeline`/`convergence`/`telemetry` views for health metrics.
+
+## Triggers
+
+Activate this skill when:
+- User runs `/dogfood` or `/exarchos:dogfood`
+- User asks "what went wrong this session" or "review the failures"
+- User wants to triage errors from a workflow run
+- End of a workflow session to capture learnings
+
+## Process
+
+### Step 1: Debug Trace via MCP Self-Service
+
+Query the MCP server's own self-service capabilities to build a ground-truth diagnostic picture. This is the primary investigation method — it uses the same tools any MCP client has access to.
+
+#### 1a. Identify Active Workflows
+
+Use `exarchos_view` with `action: "pipeline"` to get an aggregated view of active workflows with their phases and task counts.
+
+If `$ARGUMENTS` specifies a workflow or feature ID, scope to that workflow. Otherwise, inspect all non-terminal workflows.
+
+#### 1b. Inspect Workflow State and Topology
+
+For each relevant workflow:
+
+1. **Read state** — `exarchos_workflow get` to retrieve current phase, tasks, reviews, gate results.
+2. **Read topology** — `exarchos_workflow describe(topology: "<workflowType>")` to get the HSM definition. Compare the agent's phase transition attempts against valid transitions. Invalid transition attempts = documentation issue (skill prescribed wrong path) or user error.
+3. **Check guard prerequisites** — For `workflow.guard-failed` events, look up the guard in the topology to understand unmet preconditions.
+
+#### 1c. Playbook Adherence Check
+
+Use `exarchos_workflow describe(playbook: "<workflowType>")` to retrieve phase playbooks. For each phase executed, compare playbook's `tools`, `events`, `transitionCriteria`, `guardPrerequisites`, `humanCheckpoint`, and `compactGuidance` against what the agent actually did and what skill docs prescribe.
+
+**Playbook violations are diagnostic gold:**
+- Agent deviated and skill docs told it to → **documentation issue** (skill contradicts playbook)
+- Agent deviated and skill docs agree with playbook → **user error**
+- Playbook is wrong (prescribes invalid tools/events) → **code bug**
+
+#### 1d. Event Log Analysis
+
+Use `exarchos_event query(stream)` on the workflow's event stream. Look for:
+
+- **Rejected events** — absent from log despite agent attempts (corroborate with conversation errors)
+- **Missing events** — compare against playbook `events` field and `exarchos_event describe(emissionGuide: true)`. Missing model-emitted events = documentation gap or user error.
+- **Sequence anomalies** — wrong order, duplicates, or timeline gaps
+- **Schema mismatches** — use `describe(eventTypes: [...])` to get authoritative JSON Schema. Compare actual payloads against schema for semantically wrong fields.
+
+#### 1e. Orchestrate Action and Gate Analysis
+
+1. **Schema verification** — `exarchos_orchestrate describe(actions: [...])` for authoritative schemas. Compare agent's parameters against schema to detect stale skill docs or improvisation.
+2. **Gate metadata** — Describe output includes `{ blocking, dimension, autoEmits }`. Check: did the agent treat blocking/non-blocking correctly? Did expected auto-emissions fire?
+3. **Gate convergence** — `exarchos_view convergence` for per-dimension (D1-D5) pass rates. Low convergence suggests systemic gate issues.
+
+#### 1f. Runbook Conformance Check
+
+Use `exarchos_orchestrate runbook(phase)` to retrieve relevant runbooks. Check: step ordering, decision branch correctness (steps with `decide` fields), `onFail` directive adherence (`stop`/`continue`/`retry`), and `templateVars` completeness.
+
+#### 1g. Telemetry Review
+
+Use `exarchos_view telemetry` for per-tool performance. Flag: high error rates (systemic issues), high invocation counts (retry loops), and tools never invoked that the playbook prescribes.
+
+### Step 2: Scan Session for Failed Tool Calls
+
+Supplement the debug trace with client-side context — review conversation for failed Exarchos tool calls.
+
+**Note:** Platform-dependent step (requires conversation history). Skip on platforms without introspection; the debug trace is self-sufficient.
+
+**Target tools:** `exarchos_workflow`, `exarchos_event`, `exarchos_orchestrate`, `exarchos_view`, `exarchos_sync`
+
+**Error signals:** `INVALID_INPUT`, `VALIDATION_ERROR`, `BATCH_APPEND_FAILED`, Zod failures (`invalid_type`, `invalid_enum_value`, `unrecognized_keys`), `ENOENT`, `CLAIM_FAILED`, `SEQUENCE_CONFLICT`, CAS exhaustion, retry sequences, successful-after-retry calls.
+
+### Step 3: Diagnose Each Failure
+
+Merge debug trace and conversation scan findings. For each failure document:
+
+1. **What was attempted** — action, parameters, intent
+2. **What went wrong** — error message and validation path
+3. **Server-side evidence** — event log, state, describe output, views
+4. **Authoritative reference** — the self-service query providing ground truth (playbook, topology, schema, runbook)
+5. **Root cause** — per `references/root-cause-patterns.md`
+6. **Fix category** — code, docs, or user behavior
+
+Flag discrepancies only visible via server-side inspection as **trace-only findings**.
+
+### Step 4: Categorize into Buckets
+
+Assign each failure to exactly one root cause bucket:
+
+#### Bucket 1: Code Bug
+The MCP server, event store, or workflow engine has a defect.
+
+**Signals:** Schema rejects valid input (confirmed via `describe`), CAS failures with no concurrent writers, gate over-enforcement, identical-parameter retry succeeds (race condition), state corruption, topology/engine mismatch, auto-emission failure.
+
+**Action:** File bug issue with reproduction steps, expected vs actual, and suggested fix.
+
+#### Bucket 2: Documentation Issue
+Skill docs are wrong, incomplete, or out of sync with the MCP server's self-service output.
+
+**Signals:** Skill payload doesn't match `describe` schema, skill/playbook divergence, skill documents nonexistent topology paths, missing event types (compare emission guide), retry-based field discovery, runbook/skill contradictions, compactGuidance drift.
+
+**Action:** File docs issue with file:line, the discrepancy, and correct information from `describe` output.
+
+#### Bucket 3: User Error
+The agent misused a tool in a way both docs and `describe` output correctly describe.
+
+**Signals:** Format mismatch (confirmed by `describe` + docs agreement), invalid sequence (topology confirms), missing context both skill and playbook prescribe, runbook deviation without justification.
+
+**Action:** Note for skill improvement if errors are frequent.
+
+### Step 5: Generate Report
+
+Produce the report using the template from `references/report-template.md`. Include:
+- Summary counts per bucket
+- Debug trace summary (workflows inspected, events reviewed, describe queries issued, views consulted)
+- Each failure with full diagnosis (including authoritative self-service references)
+- Trace-only findings section (issues only visible via server-side inspection)
+- Playbook/runbook adherence summary
+- Actionable next steps (draft issue bodies for bugs/docs issues)
+
+### Step 6: Offer to File Issues
+
+For findings in the **Code Bug** and **Documentation Issue** buckets, offer to create GitHub issues:
+
+```bash
+gh issue create --title "<type>: <summary>" --body "<issue body>" --label "bug"
+```
+
+Only file issues with user confirmation — present the draft first.
+
+## Required Output Format
+
+```json
+{
+  "session_summary": {
+    "total_tool_calls": 0,
+    "failed_tool_calls": 0,
+    "failure_rate": "0%",
+    "debug_trace": {
+      "workflows_inspected": 0,
+      "events_reviewed": 0,
+      "describe_queries": 0,
+      "views_consulted": [],
+      "trace_only_findings": 0
+    }
+  },
+  "playbook_adherence": {
+    "phases_checked": 0,
+    "violations": [
+      {
+        "phase": "delegate",
+        "field": "events",
+        "expected": "team.spawned, team.task.assigned",
+        "actual": "none emitted",
+        "bucket": "documentation_issue"
+      }
+    ]
+  },
+  "runbook_conformance": {
+    "runbooks_checked": 0,
+    "deviations": []
+  },
+  "buckets": {
+    "code_bug": [],
+    "documentation_issue": [],
+    "user_error": []
+  },
+  "findings": [
+    {
+      "id": 1,
+      "bucket": "code_bug | documentation_issue | user_error",
+      "tool": "exarchos_workflow",
+      "action": "set",
+      "error": "INVALID_INPUT: ...",
+      "root_cause": "Schema rejects null branch on pending tasks",
+      "trace_evidence": "describe(actions: ['set']) shows branch as required string; event log confirms no task.updated event",
+      "authoritative_ref": "exarchos_workflow describe(actions: ['set']) → TaskSchema",
+      "severity": "HIGH | MEDIUM | LOW",
+      "suggested_fix": "Accept nullable branch in TaskSchema",
+      "issue_draft": {
+        "title": "bug: workflow task schema rejects null branch",
+        "labels": ["bug"],
+        "body": "..."
+      }
+    }
+  ],
+  "trace_only_findings": [
+    {
+      "id": "T1",
+      "description": "State drift: agent assumed phase was 'delegate' but server shows 'plan'",
+      "evidence": "exarchos_workflow get shows phase=plan; topology confirms plan→delegate requires planReviewComplete guard",
+      "authoritative_ref": "exarchos_workflow describe(topology: 'feature') → guards",
+      "bucket": "documentation_issue",
+      "suggested_fix": "Skill should instruct agent to verify phase via get before proceeding"
+    }
+  ]
+}
+```
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Skip the debug trace and only scan conversation | Always query MCP self-service tools first — conversation scan is supplementary |
+| Guess what the schema expects | Use `describe` to get authoritative schemas — they are the source of truth |
+| Assess playbook adherence from memory | Query `describe(playbook)` to get the actual prescribed tools, events, and criteria |
+| Assume the topology without checking | Query `describe(topology)` to get valid transitions, guards, and effects |
+| Blame the user when skill docs contradict the playbook | If skill docs diverge from playbook/describe output, it's a documentation issue |
+| File duplicate issues | Check existing open/closed issues before drafting |
+| Categorize retries as separate failures | Group retry sequences as a single finding |
+| Ignore successful-after-retry calls | These reveal friction even though they eventually worked |
+| Include non-Exarchos failures | Scope strictly to the 5 Exarchos tools — other MCP failures are out of scope |
+| Report conversation-only findings without trace corroboration | Cross-reference every finding with server-side state when possible |

package/skills/claude/dogfood/references/report-template.md

@@ -0,0 +1,109 @@
+# Dogfood Report Template
+
+```markdown
+## Dogfood Report
+
+**Session:** [workflow name or description]
+**Date:** [ISO 8601]
+**Workflow type:** [feature | debug | refactor | ad-hoc]
+
+### Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Exarchos tool calls | X |
+| Failed tool calls | Y |
+| Failure rate | Z% |
+| Code bugs found | A |
+| Documentation issues found | B |
+| User errors found | C |
+
+### Debug Trace Summary
+
+| Metric | Value |
+|--------|-------|
+| Workflows inspected | X |
+| Events reviewed | Y |
+| Describe queries issued | Z |
+| Views consulted | [pipeline, convergence, telemetry, ...] |
+| Trace-only findings | W |
+
+### Playbook Adherence
+
+| Phase | Tools | Events | Transition Criteria | Guards | Verdict |
+|-------|-------|--------|-------------------|--------|---------|
+| [phase] | [match/mismatch] | [match/mismatch] | [match/mismatch] | [match/mismatch] | [OK/VIOLATION] |
+
+**Violations:**
+- [phase]: [playbook says X, agent did Y — bucket: documentation_issue/user_error]
+
+### Runbook Conformance
+
+| Runbook | Steps Executed | Deviations | Verdict |
+|---------|---------------|------------|---------|
+| [id] | X/Y | [list] | [OK/DEVIATED] |
+
+### Code Bugs
+
+#### [CB-1] [Title]
+- **Tool:** `exarchos_workflow` action `set`
+- **Error:** `INVALID_INPUT: ...`
+- **Root cause:** [diagnosis]
+- **Trace evidence:** [what describe/view/event query revealed]
+- **Authoritative ref:** [e.g., `describe(actions: ['set']) → TaskSchema`]
+- **Impact:** [blocked workflow / degraded experience / minor friction]
+- **Suggested fix:** [specific code change]
+- **Files:** [file:line references]
+
+### Documentation Issues
+
+#### [DOC-1] [Title]
+- **Tool:** `exarchos_event` action `append`
+- **Error:** `VALIDATION_ERROR: invalid_enum_value`
+- **Root cause:** [diagnosis — what the docs say vs what describe output shows]
+- **Trace evidence:** [describe output vs skill doc content]
+- **Authoritative ref:** [e.g., `describe(eventTypes: ['team.spawned']) → JSON Schema`]
+- **Skill/Reference:** [skills/X/SKILL.md:line or references/Y.md:line]
+- **Source of truth:** [describe action + servers/exarchos-mcp/src/file.ts:line]
+- **Suggested fix:** [update docs to match describe output]
+
+### User Errors
+
+#### [UE-1] [Title]
+- **Tool:** `exarchos_orchestrate` action `check_tdd_compliance`
+- **Error:** [error message]
+- **What happened:** [agent did X]
+- **What should have happened:** [both docs and describe agree on Y]
+- **Authoritative ref:** [confirm docs match describe/topology/playbook]
+- **Skill improvement:** [if the error is common, suggest making the skill clearer]
+
+### Trace-Only Findings
+
+Issues discovered solely through debug trace (not visible in conversation errors):
+
+#### [T-1] [Title]
+- **Discovery method:** [describe comparison / event log analysis / view query / playbook check]
+- **Evidence:** [what the trace revealed]
+- **Authoritative ref:** [which self-service query provided the ground truth]
+- **Bucket:** [code_bug / documentation_issue]
+- **Impact:** [silent data loss / state drift / stale guidance / playbook-skill divergence]
+- **Suggested fix:** [specific change]
+
+### Issue Drafts
+
+Ready-to-file issue bodies for Code Bugs and Documentation Issues:
+
+#### Issue: [CB-1 title]
+```
+gh issue create --title "bug: [summary]" --label "bug" --body "..."
+```
+
+#### Issue: [DOC-1 title]
+```
+gh issue create --title "docs: [summary]" --label "bug" --body "..."
+```
+
+### Patterns & Trends
+
+[Observations about recurring failure modes, systemic issues, or improvements to the dogfood process itself]
+```

package/skills/claude/dogfood/references/root-cause-patterns.md

@@ -0,0 +1,227 @@
+# Root Cause Patterns
+
+Common failure patterns observed from dogfooding Exarchos workflows. Use this reference to quickly diagnose failures during `/dogfood` triage.
+
+Each pattern includes a **Debug trace check** showing which MCP self-service queries to run for diagnosis. These queries use the same platform-agnostic tools available to any MCP client.
+
+---
+
+## Code Bug Patterns
+
+### Schema Too Strict
+**Symptom:** Zod validation rejects input that should be valid.
+**Examples:**
+- `branch: null` rejected on pending tasks (should be nullable)
+- `status: "completed"` rejected (only accepts `"complete"`)
+- Required fields that should be optional for certain task states
+
+**Diagnosis:** Compare the rejected input against the Zod schema in `servers/exarchos-mcp/src/`. If the input represents a valid real-world state, the schema is too strict.
+
+**Debug trace check:** Use `exarchos_workflow describe(actions: ['set'])` or `exarchos_event describe(eventTypes: ['...'])` to get the authoritative JSON Schema. Compare the rejected field's type/constraints against the schema output. If the schema is stricter than the domain allows, it's a code bug.
+
+**Historical:** #876 (null branch), #941 (completed vs complete)
+
+### Stale Cache / Sequence Divergence
+**Symptom:** CAS retry loop exhaustion, `CLAIM_FAILED`, `SEQUENCE_CONFLICT` with no concurrent writers.
+**Examples:**
+- `.seq` file from prior session disagrees with JSONL line count
+- All retries produce the same mismatch
+
+**Diagnosis:** Check if the error occurs on first attempt with no other agents running. If so, it's a stale cache issue, not concurrency.
+
+**Debug trace check:** Use `exarchos_event query(stream)` to count events and compare against the sequence number in the error. Use `exarchos_view telemetry` to check if there are concurrent tool invocations. A mismatch with no interleaved writers confirms stale cache.
+
+**Historical:** #939 (stale .seq cache)
+
+### Gate Over-Enforcement
+**Symptom:** Workflow blocked by a gate that doesn't apply to the current task type.
+**Examples:**
+- TDD compliance gate blocks documentation-only tasks
+- Manual evidence parameter accepted but not consulted for bypass
+
+**Diagnosis:** Check if the gate has exemption logic for the task's characteristics (file types changed, task category). If not, the gate needs conditional enforcement.
+
+**Debug trace check:** Use `exarchos_orchestrate describe(actions: ['check_tdd_compliance'])` to inspect gate metadata (blocking, dimension). Use `exarchos_view convergence` to see if this gate is systematically failing. Use `exarchos_workflow get` to check task metadata that should trigger exemptions.
+
+**Historical:** #940 (TDD gate on docs-only tasks)
+
+### Silent State Corruption
+**Symptom:** Debug trace reveals workflow state that doesn't match the event log. Only visible via server-side inspection — the conversation shows no errors.
+**Examples:**
+- Events accepted but state not updated (projection bug)
+- Phase field shows a value that no transition event supports
+- Task status regressed to a prior state
+
+**Diagnosis:** Compare the event stream (chronological record of what happened) against the current workflow state (projected view). If the state can't be derived from the event sequence, there's a projection or state-rebuild bug.
+
+**Debug trace check:** Read full event log via `exarchos_event query(stream)`, then read state via `exarchos_workflow get`. Walk the events forward and verify the final state matches. Use `exarchos_workflow reconcile` to see if reconciliation produces a different state — if so, the live projection diverged.
+
+### Topology/Engine Mismatch
+**Symptom:** HSM topology defines a transition but the engine rejects it, or vice versa.
+**Examples:**
+- Agent attempts a transition that exists in `describe(topology)` but gets `INVALID_TRANSITION`
+- Guard defined in topology never fires (guard handler not registered)
+- Effect defined in topology doesn't produce expected side effect
+
+**Diagnosis:** Compare `exarchos_workflow describe(topology)` output against actual engine behavior. The topology is the declared specification; if the engine doesn't honor it, the engine has a bug.
+
+**Debug trace check:** Use `describe(topology: '<workflowType>')` to get the full HSM definition. Identify the transition the agent attempted. Check guards, effects, and target state. Then check `workflow.guard-failed` events in the log for the specific guard that blocked it. If the guard isn't in the topology definition but still fires, the engine has undeclared guards.
+
+### Auto-Emission Failure
+**Symptom:** An action's gate metadata declares `autoEmits` events, but those events don't appear in the event log after the action succeeds.
+**Examples:**
+- `task_complete` should auto-emit `task.completed` but no such event appears
+- `check_tdd_compliance` should auto-emit `gate.executed` but the gate event is missing
+
+**Diagnosis:** Compare `exarchos_orchestrate describe(actions: ['<action>'])` auto-emission metadata against `exarchos_event query(stream)` filtered for the expected event type after the action's timestamp.
+
+**Debug trace check:** Run `describe(actions: ['<action>'])` → note `autoEmits` field. Query event log filtered by type and time range. If the event is missing, the auto-emission handler has a bug.
+
+---
+
+## Documentation Issue Patterns
+
+### Schema-Doc Drift
+**Symptom:** Agent constructs payloads from skill doc examples that fail Zod validation. Multiple retries with different field names.
+**Examples:**
+- Skill doc shows `gate` field, actual schema requires `gateName`
+- Skill doc omits required fields like `taskId`
+- Skill doc includes fields (`prNumbers`, `maxIterations`) that aren't in the schema
+
+**Diagnosis:** Compare the example payloads in skill docs against the `describe` output. The `describe` API returns the authoritative JSON Schema — it is the source of truth.
+
+**Debug trace check:** Use `exarchos_orchestrate describe(actions: ['<action>'])` or `exarchos_event describe(eventTypes: ['<type>'])` to get the authoritative schema. Diff field names, types, and required status against what skill docs prescribe. Any mismatch is schema-doc drift.
+
+**Historical:** #964 (shepherd event payloads)
+
+### Unknown Valid Values
+**Symptom:** Agent guesses enum values and fails with `invalid_enum_value`.
+**Examples:**
+- Agent tries `wave.completed` when valid type is `workflow.transition`
+- Agent doesn't know which event types exist
+
+**Diagnosis:** Check if the skill docs list the valid enum values. If not, the agent has to guess — that's a documentation gap.
+
+**Debug trace check:** Use `exarchos_event describe(emissionGuide: true)` to get the full event type catalog organized by emission source (auto/model/hook/planned). Cross-reference against what skill docs list. Missing types in the skill docs = documentation gap.
+
+**Historical:** #741 (unknown event types)
+
+### Path Resolution
+**Symptom:** `ENOENT` errors when scripts are invoked via documented paths.
+**Examples:**
+- Skill references `scripts/check-tdd-compliance.sh` but script lives at `~/.claude/scripts/`
+- MCP orchestrate `spawnSync` fails because CWD isn't the exarchos install dir
+
+**Diagnosis:** Check if the script exists at the path referenced in the skill docs. Then check where the installer actually places it. Mismatch = path resolution bug.
+
+**Debug trace check:** Use `exarchos_orchestrate describe(actions: ['<action>'])` to verify what the server expects for script paths. If the describe output shows a different path convention than skill docs, the docs need updating.
+
+**Historical:** #942 (scripts/ relative to CWD)
+
+### Playbook-Skill Divergence
+**Symptom:** Playbook prescribes tools, events, or transition criteria that differ from what the skill docs instruct. Agent follows skill docs and fails; playbook had the correct answer.
+**Examples:**
+- Skill says to emit `team.started`, playbook says to emit `team.spawned`
+- Skill says phase transitions on "all tasks complete", playbook says it also requires `teamDisbanded`
+- Skill doesn't mention a human checkpoint that the playbook requires
+- Skill lists 3 tools for a phase, playbook lists 5
+
+**Diagnosis:** The playbook is the source of truth for phase behavior (it's served by the MCP server). If skill docs diverge, they need updating.
+
+**Debug trace check:** Use `exarchos_workflow describe(playbook: '<workflowType>')` and compare each phase's `tools`, `events`, `transitionCriteria`, `guardPrerequisites`, and `humanCheckpoint` against the corresponding skill SKILL.md sections. Flag structural contradictions.
+
+### Runbook-Skill Divergence
+**Symptom:** Runbook prescribes steps or decision logic that differs from skill docs. Agent follows skill and misses steps or takes the wrong branch.
+**Examples:**
+- Skill says to run gates in order A-B-C, runbook says A-C-B
+- Skill's track selection logic doesn't match the decision runbook's branches
+- Skill doesn't mention required `templateVars` that the runbook expects
+
+**Diagnosis:** Decision runbooks are authoritative for decision logic; linear runbooks are authoritative for step ordering. If skill docs encode their own decision trees that don't match, the skill needs updating.
+
+**Debug trace check:** Use `exarchos_orchestrate runbook(phase: '<phase>')` to get the resolved runbook. Compare step ordering and decision branches against skill instructions. For decision runbooks, check that the skill references the runbook rather than encoding inline logic.
+
+### Missing Workflow Instructions
+**Symptom:** Orchestrator skips required tool calls or doesn't follow the expected workflow.
+**Examples:**
+- Delegation phase uses Claude Code Task/TaskUpdate but never calls `exarchos_workflow set`
+- No events emitted during an entire workflow phase
+- PR bodies don't follow the template
+
+**Diagnosis:** Check if the skill docs explicitly instruct the agent to make these tool calls. If not, the agent has no reason to — the docs need to prescribe the correct workflow.
+
+**Debug trace check:** Use `exarchos_event query(stream)` and filter by phase. An empty or sparse event log for a phase that should have activity indicates the agent was never told to emit events. Cross-reference with `describe(playbook)` to see what the playbook prescribes.
+
+**Historical:** #739 (no exarchos tools during delegation), #740 (no events), #907 (PR template)
+
+### Describe-Doc Divergence
+**Symptom:** Debug trace reveals that MCP `describe` responses contain information that contradicts or supersedes what skill docs say.
+**Examples:**
+- Skill doc says phase X has no gates, but `describe(topology)` shows a guard on the transition
+- Skill doc lists 3 required event fields, but `describe(eventTypes)` shows 5
+- CompactGuidance mentions an anti-pattern the skill doc doesn't cover
+- Gate metadata shows `blocking: true` but skill says it's advisory
+
+**Diagnosis:** The describe API is the source of truth for platform-agnostic workflow metadata. If skill docs diverge from describe responses, the skill docs need updating.
+
+**Debug trace check:** For each failure, query the relevant describe endpoint and compare its output against the skill doc that the agent was following. The discrepancy IS the documentation issue.
+
+---
+
+## User Error Patterns
+
+### Sequence Violation
+**Symptom:** Tool call fails because a prerequisite wasn't met.
+**Examples:**
+- Quality review dispatched before spec review passes
+- Synthesis attempted before review phase completes
+- Task completion attempted without required gate events
+
+**Diagnosis:** Check if the skill docs describe the prerequisite. If they do and the agent skipped it, it's user error. If they don't, it's a documentation issue.
+
+**Debug trace check:** Use `exarchos_workflow describe(topology)` to verify the transition's guards. If the guard that blocked the agent is documented in both the topology and skill docs, the agent should have known.
+
+### Parameter Format Mismatch
+**Symptom:** Tool call fails with wrong type or format, and the correct format is documented.
+**Examples:**
+- Passing a number where a string is expected
+- Using camelCase when kebab-case is required
+- Missing required field that the skill docs explicitly list
+
+**Diagnosis:** If the skill docs clearly show the correct format and the agent didn't follow them, it's user error. If the docs are ambiguous or show the wrong format, it's a documentation issue.
+
+**Debug trace check:** Use the appropriate `describe` action to confirm the schema matches what skill docs say. If both agree and the agent deviated, it's user error.
+
+### Runbook Deviation
+**Symptom:** Agent deviated from runbook step ordering or decision branches without justification.
+**Examples:**
+- Skipped a step marked `onFail: "stop"`
+- Took a decision branch inconsistent with the `source` field's value
+- Didn't supply required `templateVars`
+
+**Diagnosis:** If the runbook is accessible via `exarchos_orchestrate runbook()` and the skill docs reference it, the agent should have followed it. Deviation without cause is user error.
+
+**Debug trace check:** Use `exarchos_orchestrate runbook(id: '<id>')` to get the resolved steps. Map agent's actual execution against the step list.
+
+### Context Loss After Compaction
+**Symptom:** Agent loses track of state, teammates, or in-progress work after context compaction.
+**Examples:**
+- Orchestrator re-dispatches already-completed tasks
+- Agent doesn't check workflow state after resume
+- Agent creates duplicate branches
+
+**Diagnosis:** Check if the skill docs include post-compaction recovery instructions. If they do, this is user error. If not, the skill needs compaction-resilience instructions (likely a documentation issue).
+
+**Debug trace check:** Use `exarchos_workflow get` to see actual state. If the agent's assumptions diverge from server state after compaction, and the skill instructs re-orientation via `exarchos_workflow get` or `exarchos_view pipeline`, the agent should have re-checked.
+
+**Historical:** #738 (lost teammates after compaction)
+
+---
+
+## Severity Guide
+
+| Severity | Definition | Filing Priority |
+|----------|-----------|----------------|
+| **HIGH** | Blocks workflow progression, no workaround, or causes data loss | File immediately |
+| **MEDIUM** | Degraded experience, workaround exists (e.g., change field value, use different path) | File in batch |
+| **LOW** | Minor friction, single retry resolves it | Track for patterns, file if recurrent |

package/skills/{git-worktrees → claude/git-worktrees}/SKILL.md

@@ -71,9 +71,8 @@ Run baseline tests to ensure the worktree is ready:
 
 ```typescript
 exarchos_orchestrate({
-  action: "run_script",
-  script: "verify-worktree-baseline.sh",
-  args: ["--worktree-path", ".worktrees/task-name"]
+  action: "verify_worktree_baseline",
+  worktreePath: ".worktrees/task-name"
 })
 ```
 
@@ -126,8 +125,7 @@ Run the worktree verification script before any file modifications:
 
 ```typescript
 exarchos_orchestrate({
-  action: "run_script",
-  script: "verify-worktree.sh"
+  action: "verify_worktree"
 })
 ```
 
@@ -135,9 +133,8 @@ To check a specific path instead of the current directory:
 
 ```typescript
 exarchos_orchestrate({
-  action: "run_script",
-  script: "verify-worktree.sh",
-  args: ["--cwd", "/path/to/.worktrees/task-name"]
+  action: "verify_worktree",
+  cwd: "/path/to/.worktrees/task-name"
 })
 ```
 
@@ -153,7 +150,7 @@ Include in all implementer prompts:
 
 Before making ANY file changes, run:
 
-    exarchos_orchestrate({ action: "run_script", script: "verify-worktree.sh" })
+    exarchos_orchestrate({ action: "verify_worktree" })
 
 If `passed: false`: STOP and report error.
 DO NOT proceed with any modifications outside a worktree.