@lvlup-sw/exarchos 2.0.1

package/skills/debug/references/state-schema.md

@@ -0,0 +1,294 @@
+# Debug Workflow State Schema
+
+Extended schema for debug workflow state files.
+
+## Base Schema
+
+Debug workflows extend the standard workflow state with additional fields.
+
+```json
+{
+  "version": "1.1",
+  "featureId": "debug-<issue-slug>",
+  "workflowType": "debug",
+  "createdAt": "ISO8601",
+  "updatedAt": "ISO8601",
+  "track": "hotfix | thorough",
+  "phase": "triage | investigate | rca | design | debug-implement | debug-validate | debug-review | hotfix-implement | hotfix-validate | synthesize | completed | cancelled | blocked",
+
+  "urgency": {
+    "level": "P0 | P1 | P2",
+    "justification": "string"
+  },
+
+  "triage": {
+    "symptom": "string",
+    "reproduction": "string | null",
+    "affectedArea": "string",
+    "impact": "string"
+  },
+
+  "investigation": {
+    "startedAt": "ISO8601 | null",
+    "completedAt": "ISO8601 | null",
+    "rootCause": "string | null",
+    "findings": ["string"]
+  },
+
+  "artifacts": {
+    "rca": "string | null",
+    "fixDesign": "string | null",
+    "pr": "string | null"
+  },
+
+  "followUp": {
+    "rcaRequired": "boolean",
+    "issueUrl": "string | null"
+  },
+
+  "tasks": [],
+  "worktrees": {},
+  "reviews": {},
+  "synthesis": {
+    "integrationBranch": "string | null",
+    "mergeOrder": [],
+    "mergedBranches": [],
+    "prUrl": "string | null",
+    "prFeedback": []
+  }
+}
+```
+
+## Field Definitions
+
+### Top-Level Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | string | Schema version, currently "1.1" |
+| `featureId` | string | Unique identifier, format: `debug-<issue-slug>` |
+| `workflowType` | string | Always "debug" for debug workflows |
+| `createdAt` | ISO8601 | When workflow was created |
+| `updatedAt` | ISO8601 | Last modification timestamp |
+| `track` | enum | "hotfix" or "thorough" |
+| `phase` | enum | Current workflow phase |
+
+### Phase Values
+
+| Track    | Valid Phases                                                                          |
+|----------|-----------------------------------------------------------------------------------------|
+| Hotfix   | triage → investigate → hotfix-implement → hotfix-validate → completed                                 |
+| Thorough | triage → investigate → rca → design → debug-implement → debug-validate → debug-review → synthesize → completed |
+
+Note: Thorough track may skip `rca` and `design` phases if root cause is straightforward.
+
+### Urgency Object
+
+```json
+{
+  "urgency": {
+    "level": "P0",
+    "justification": "Production login broken, 100% of users affected"
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `level` | enum | P0 (critical), P1 (high), P2 (normal) |
+| `justification` | string | Why this urgency level was selected |
+
+### Triage Object
+
+```json
+{
+  "triage": {
+    "symptom": "Login returns 500 error",
+    "reproduction": "Click login button with valid credentials",
+    "affectedArea": "src/auth/login.ts",
+    "impact": "All users cannot log in"
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `symptom` | string | Observable problem description |
+| `reproduction` | string\|null | Steps to reproduce, null if unknown |
+| `affectedArea` | string | Suspected code area or component |
+| `impact` | string | Business/user impact description |
+
+### Investigation Object
+
+```json
+{
+  "investigation": {
+    "startedAt": "2026-01-27T10:00:00Z",
+    "completedAt": "2026-01-27T10:15:00Z",
+    "rootCause": "Session cookie SameSite attribute mismatch",
+    "findings": [
+      "Error occurs in handleLogin function",
+      "Session object is null when it shouldn't be",
+      "Cookie not being set due to browser security policy"
+    ]
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `startedAt` | ISO8601\|null | When investigation began |
+| `completedAt` | ISO8601\|null | When root cause was found |
+| `rootCause` | string\|null | Final root cause determination |
+| `findings` | string[] | Progressive findings during investigation |
+
+### Artifacts Object
+
+```json
+{
+  "artifacts": {
+    "rca": "docs/rca/2026-01-27-login-500-error.md",
+    "fixDesign": "Set SameSite=None on session cookie, add Secure flag",
+    "pr": "https://github.com/org/repo/pull/123"
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `rca` | string\|null | Path to RCA document (thorough track only) |
+| `fixDesign` | string\|null | Brief fix description (in state, not separate doc) |
+| `pr` | string\|null | Pull request URL |
+
+### Follow-Up Object
+
+```json
+{
+  "followUp": {
+    "rcaRequired": true,
+    "issueUrl": "https://github.com/org/repo/issues/456"
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `rcaRequired` | boolean | True if hotfix shipped without full RCA |
+| `issueUrl` | string\|null | Link to follow-up issue for RCA |
+
+## State Transitions
+
+### Hotfix Track
+
+```text
+triage → investigate → hotfix-implement → hotfix-validate → completed
+   │          │               │                 │                │
+   │          │               │                 │                └─ Human checkpoint: merge
+   │          │               │                 └─ Run smoke tests
+   │          │               └─ Apply minimal fix
+   │          └─ Find root cause (15 min max)
+   └─ Gather context, select track
+```
+
+### Thorough Track
+
+```text
+triage → investigate → rca → design → debug-implement → debug-validate → debug-review → synthesize → completed
+   │          │         │       │            │                 │              │              │          │
+   │          │         │       │            │                 │              │              │          └─ Merge
+   │          │         │       │            │                 │              │              └─ Create PR
+   │          │         │       │            │                 │              └─ Spec review
+   │          │         │       │            │                 └─ Run validation
+   │          │         │       │            └─ TDD implementation
+   │          │         │       └─ Brief fix approach
+   │          │         └─ Full RCA document
+   │          └─ Systematic investigation
+   └─ Gather context, select track
+```
+
+## Example State Files
+
+### Hotfix In Progress
+
+```json
+{
+  "version": "1.1",
+  "featureId": "debug-login-500",
+  "workflowType": "debug",
+  "createdAt": "2026-01-27T10:00:00Z",
+  "updatedAt": "2026-01-27T10:12:00Z",
+  "track": "hotfix",
+  "phase": "hotfix-implement",
+  "urgency": {
+    "level": "P0",
+    "justification": "Production login broken"
+  },
+  "triage": {
+    "symptom": "Login returns 500",
+    "reproduction": "Click login with valid creds",
+    "affectedArea": "src/auth/login.ts",
+    "impact": "All users blocked"
+  },
+  "investigation": {
+    "startedAt": "2026-01-27T10:02:00Z",
+    "completedAt": "2026-01-27T10:10:00Z",
+    "rootCause": "Missing null check on session",
+    "findings": [
+      "Error in handleLogin line 42",
+      "Session is null when user has no prior session"
+    ]
+  },
+  "artifacts": {
+    "rca": null,
+    "fixDesign": "Add null check before accessing session properties",
+    "pr": null
+  },
+  "followUp": {
+    "rcaRequired": true,
+    "issueUrl": null
+  }
+}
+```
+
+### Thorough Completed
+
+```json
+{
+  "version": "1.1",
+  "featureId": "debug-cart-total-wrong",
+  "workflowType": "debug",
+  "createdAt": "2026-01-26T14:00:00Z",
+  "updatedAt": "2026-01-27T09:00:00Z",
+  "track": "thorough",
+  "phase": "completed",
+  "urgency": {
+    "level": "P2",
+    "justification": "Cart shows wrong total, workaround is refresh"
+  },
+  "triage": {
+    "symptom": "Cart total doesn't update after removing item",
+    "reproduction": "Add 2 items, remove 1, total shows both",
+    "affectedArea": "src/cart/CartTotal.tsx",
+    "impact": "Users confused, may abandon checkout"
+  },
+  "investigation": {
+    "startedAt": "2026-01-26T14:05:00Z",
+    "completedAt": "2026-01-26T15:30:00Z",
+    "rootCause": "React state not updating due to stale closure in useEffect",
+    "findings": [
+      "Total computed in useEffect",
+      "Effect has stale items reference",
+      "Missing items in dependency array"
+    ]
+  },
+  "artifacts": {
+    "rca": "docs/rca/2026-01-26-cart-total-wrong.md",
+    "fixDesign": "Add items to useEffect deps, use useMemo for total",
+    "pr": "https://github.com/org/repo/pull/789"
+  },
+  "followUp": {
+    "rcaRequired": false,
+    "issueUrl": null
+  }
+}
+```

package/skills/debug/references/thorough-track.md

@@ -0,0 +1,194 @@
+---
+name: thorough-track
+---
+
+# Thorough Track
+
+## Purpose
+
+Fix bugs with proper rigor. Capture institutional knowledge through RCA.
+
+## Phases
+
+```
+Triage -> Investigate -> RCA -> Design -> Implement -> Review -> Synthesize -> Completed
+  |          |          |       |         |          |          |           |
+  |          |          |       |         |          |          |           +- Merge
+  |          |          |       |         |          |          +- Create PR
+  |          |          |       |         |          +- Spec review only
+  |          |          |       |         +- TDD in worktree
+  |          |          |       +- Brief fix approach
+  |          |          +- Full RCA document
+  |          +- Systematic investigation
+  +- Capture symptom, select track
+```
+
+## Phase Details
+
+### 1. Triage Phase
+
+Same as hotfix, but set track to "thorough":
+
+**Set track and advance to investigate:**
+
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "track": "thorough"
+}, phase: "investigate"
+```
+
+### 2. Investigate Phase
+
+Use `@skills/debug/references/investigation-checklist.md`.
+
+No time limit. Be thorough:
+- Use Task tool with Explore agent for complex investigation
+- Document all findings
+- Understand the full picture before proposing fix
+
+### 3. RCA Phase
+
+Create RCA document using `@skills/debug/references/rca-template.md`.
+
+Save to: `docs/rca/YYYY-MM-DD-<issue-slug>.md`
+
+Update state:
+
+**Record RCA artifact and advance to design:**
+
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "artifacts.rca": "docs/rca/YYYY-MM-DD-<issue-slug>.md"
+}, phase: "design"
+```
+
+### 4. Design Phase
+
+Brief fix approach (NOT a full design document).
+
+2-3 paragraphs max in state file:
+
+**Record fix design and advance to implement:**
+
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "artifacts.fixDesign": "<fix approach description>"
+}, phase: "implement"
+```
+
+### 5. Implement Phase
+
+Create worktree and implement with TDD:
+
+```bash
+# Create worktree
+git branch feature/debug-<issue-slug> main
+git worktree add .worktrees/debug-<issue-slug> feature/debug-<issue-slug>
+cd .worktrees/debug-<issue-slug> && npm install
+
+# TDD: Write failing test first, then implement
+```
+
+Update state:
+
+**Record worktree and advance to review:**
+
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "worktrees.\".worktrees/debug-<issue-slug>\"": {
+    "branch": "feature/debug-<issue-slug>",
+    "status": "active"
+  }
+}, phase: "review"
+```
+
+### 6. Review Phase
+
+Spec review only (not quality review - this is a fix, not new feature).
+
+Run the debug review gate to verify test coverage for the bug fix:
+
+```bash
+scripts/debug-review-gate.sh --repo-root <path> --base-branch <branch>
+```
+
+**On exit 0:** Review passed -- tests added and passing.
+**On exit 1:** Gaps found -- missing tests or regressions.
+
+Additionally verify:
+- [ ] Fix matches RCA root cause
+- [ ] Fix matches design approach
+
+Update state:
+
+**Advance to synthesize:**
+
+```
+action: "set", featureId: "debug-<issue-slug>", phase: "synthesize"
+```
+
+### 7. Synthesize Phase
+
+Create PR via Graphite MCP:
+
+```
+# Stage and create branch with fix commit
+mcp__graphite__run_gt_cmd({ args: ["create", "-m", "fix: <issue summary>"], cwd: "<repo-root>" })
+
+# Submit to create the PR
+mcp__graphite__run_gt_cmd({ args: ["submit", "--no-interactive", "--publish", "--merge-when-ready"], cwd: "<repo-root>" })
+```
+
+Then update the PR description:
+```bash
+gh pr edit <number> --body "## Summary
+[Brief description]
+
+## Root Cause Analysis
+See: docs/rca/YYYY-MM-DD-<issue-slug>.md
+
+## Changes
+- [change 1]
+
+## Test Plan
+- [test approach]"
+```
+
+> Or use GitHub MCP `update_pull_request` if available.
+
+**Human checkpoint:** Confirm merge.
+
+## Track Switching
+
+### Hotfix -> Thorough
+
+When `scripts/investigation-timer.sh` exits with code 1 (budget exceeded), switch to thorough track:
+
+**Switch to thorough track:**
+
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "track": "thorough",
+  "investigation.findings": ["Switched to thorough track: root cause not found in 15 min"]
+}
+```
+
+Continue investigation without time constraint.
+
+### Thorough -> Escalate
+
+If fix requires architectural changes:
+
+**Escalate to blocked:**
+
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "investigation.findings": ["Escalated: requires architectural changes"]
+}, phase: "blocked"
+```
+
+Output to user:
+> This issue requires architectural changes that exceed bug fix scope.
+> Recommend running `/exarchos:ideate` to design the solution properly.
+>
+> Context preserved in: `<state-file>`

package/skills/debug/references/triage-questions.md

@@ -0,0 +1,155 @@
+# Triage Questions
+
+Use these questions during the triage phase to gather context and select the appropriate track.
+
+## Core Questions
+
+### 1. What is the symptom?
+
+Capture the observable problem:
+- Error messages (exact text)
+- Unexpected behavior
+- Performance degradation
+- Data corruption/loss
+
+**Prompts:**
+- "What error message do you see?"
+- "What behavior are you observing?"
+- "What did you expect to happen instead?"
+
+### 2. Can it be reproduced?
+
+Determine reproducibility:
+- **Always** - Happens every time
+- **Sometimes** - Intermittent, conditions unclear
+- **Rarely** - Happened once, hard to trigger
+- **Unknown** - Haven't tried yet
+
+**Prompts:**
+- "Can you trigger this consistently?"
+- "What steps reproduce the issue?"
+- "Does it happen in all environments?"
+
+### 3. What is the impact/urgency?
+
+Assess business impact to determine urgency level:
+
+| Level | Criteria | Examples |
+|-------|----------|----------|
+| **P0** | Production down, revenue impact, data loss | Site unreachable, payments failing, user data corrupted |
+| **P1** | Major feature broken, significant user impact | Login fails for subset, core workflow blocked |
+| **P2** | Minor issue, workaround exists, cosmetic | UI glitch, slow performance, edge case failure |
+
+**Prompts:**
+- "How many users are affected?"
+- "Is there a workaround?"
+- "Is this blocking production use?"
+
+### 4. What area of code is likely affected?
+
+Narrow down the investigation scope:
+- Component/module name
+- File paths if known
+- Recent changes that might relate
+- Related features
+
+**Prompts:**
+- "Which feature/page does this affect?"
+- "Were there recent deployments?"
+- "Has this worked before? When did it break?"
+
+## Track Selection Logic
+
+Based on answers, select the appropriate track:
+
+```
+                    ┌─────────────┐
+                    │   P0 / P1   │
+                    │  severity?  │
+                    └──────┬──────┘
+                           │
+              ┌────────────┼────────────┐
+              │            │            │
+           P0 + Known   P0 + Unknown   P1 or P2
+           Root Cause   Root Cause
+              │            │            │
+              ▼            ▼            ▼
+         ┌─────────┐  ┌─────────┐  ┌─────────┐
+         │ HOTFIX  │  │ Attempt │  │THOROUGH │
+         │  TRACK  │  │ Hotfix  │  │  TRACK  │
+         └─────────┘  │ 15 min  │  └─────────┘
+                      └────┬────┘
+                           │
+                      ┌────┴────┐
+                      │  Found  │
+                      │ in 15m? │
+                      └────┬────┘
+                      Yes  │  No
+                       ┌───┴───┐
+                       ▼       ▼
+                   HOTFIX   THOROUGH
+                    TRACK    TRACK
+```
+
+### Hotfix Track Criteria
+
+Select hotfix when ALL of these apply:
+- [ ] P0 urgency (production down or revenue impact)
+- [ ] Root cause is known OR likely findable in 15 minutes
+- [ ] Fix is straightforward (code change, config fix, rollback)
+- [ ] User accepts reduced ceremony for speed
+
+### Thorough Track Criteria
+
+Select thorough when ANY of these apply:
+- [ ] P1/P2 urgency (not production-critical)
+- [ ] Root cause is unknown and complex
+- [ ] Fix requires design decisions
+- [ ] Issue is recurring or indicates systemic problem
+- [ ] User wants full documentation for learning
+
+### Escalation Criteria
+
+Escalate to `/exarchos:ideate` when:
+- [ ] Fix requires architectural changes
+- [ ] Multiple systems/teams need coordination
+- [ ] Issue exposes design flaw requiring redesign
+- [ ] Scope exceeds bug fix (becomes feature work)
+
+## Triage Output Format
+
+After gathering answers, record in state file:
+
+```json
+{
+  "triage": {
+    "symptom": "Login button returns 500 error on click",
+    "reproduction": "Always reproducible: Click login with valid credentials",
+    "affectedArea": "Authentication service, src/auth/login.ts",
+    "impact": "All users cannot log in"
+  },
+  "urgency": {
+    "level": "P0",
+    "justification": "Production login completely broken, 100% of users affected"
+  },
+  "track": "hotfix"
+}
+```
+
+## Quick Triage Script
+
+For fast P0 situations, use this abbreviated flow:
+
+1. **Symptom?** [one sentence]
+2. **Repro?** [yes/no/unknown]
+3. **P0?** [yes → hotfix, no → thorough]
+4. **Affected file?** [path or "unknown"]
+
+Example:
+```
+Symptom: Login 500 error
+Repro: Yes
+P0: Yes
+File: src/auth/login.ts
+→ HOTFIX TRACK
+```

package/skills/debug/references/troubleshooting.md

@@ -0,0 +1,47 @@
+---
+name: troubleshooting
+---
+
+# Troubleshooting
+
+## MCP Tool Call Failed
+If an Exarchos MCP tool returns an error:
+1. Check the error message -- it usually contains specific guidance
+2. Verify the workflow state exists: call `mcp__exarchos__exarchos_workflow` with `action: "get"` and the featureId
+3. If "version mismatch": another process updated state -- retry the operation
+4. If state is corrupted: call `mcp__exarchos__exarchos_workflow` with `action: "cancel"` and `dryRun: true`
+
+## State Desync
+If workflow state doesn't match git reality:
+1. The SessionStart hook runs reconciliation automatically on resume
+2. If manual check needed: compare state file with `git log` and branch state
+3. Update state via `mcp__exarchos__exarchos_workflow` with `action: "set"` to match git truth
+
+## Investigation Timeout (Hotfix Track)
+If 15-minute investigation timer expires without root cause:
+1. The workflow auto-switches to thorough track
+2. All investigation findings are preserved in state
+3. Continue investigation without time constraint
+
+## Track Switching
+If hotfix track reveals complexity requiring thorough investigation:
+1. Call `mcp__exarchos__exarchos_workflow` with `action: "set"` to update track to "thorough"
+2. Previous investigation findings carry over
+3. RCA phase begins after investigation completes
+
+## Exarchos Integration
+
+When Exarchos MCP tools are available, emit events throughout the debug workflow:
+
+1. **At workflow start (triage):** `mcp__exarchos__exarchos_event` with `action: "append"` -> `workflow.started` with workflowType "debug", urgency
+2. **On track selection:** `mcp__exarchos__exarchos_event` with `action: "append"` -> `phase.transitioned` with selected track (hotfix/thorough)
+3. **On each phase transition:** `mcp__exarchos__exarchos_event` with `action: "append"` -> `phase.transitioned` from->to
+4. **Thorough track stacking:** Handled by `/exarchos:synthesize` (Graphite stack submission)
+5. **Hotfix track commit:** Single `gt create -m "fix: <description>"` -- no multi-branch stacking needed
+6. **On complete:** `mcp__exarchos__exarchos_event` with `action: "append"` -> `phase.transitioned` to "completed"
+
+## Performance Notes
+
+- Complete each step fully before advancing -- quality over speed
+- Do not skip validation checks even when the change appears trivial
+- Complete each investigation step before concluding root cause. Do not jump to fix without evidence.