@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/codex/debug/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: debug
+description: "Bug investigation and fix workflow. Triggers: 'debug', 'fix bug', 'investigate issue', 'something is broken', or /debug. Hotfix track for quick fixes, thorough track for root cause analysis. Do NOT use for feature development or refactoring. Do NOT escalate to /ideate unless the fix requires architectural redesign."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity:
+    - triage
+    - investigate
+    - rca
+    - design
+    - debug-implement
+    - debug-validate
+    - debug-review
+    - hotfix-implement
+    - hotfix-validate
+    - synthesize
+---
+
+# Debug Workflow Skill
+
+## Overview
+
+Investigation-first workflow for debugging and regression fixes. Provides two tracks based on urgency: hotfix (fast, minimal ceremony) and thorough (rigorous, full RCA documentation).
+
+## Triggers
+
+Activate this skill when:
+- User runs `debug` command
+- User reports a bug or regression
+- User needs to investigate an error
+- User says "fix this bug" or similar
+
+**Disambiguation:** If the user says "fix" or "clean up" — use `debug` when something is *broken* (error, crash, wrong behavior). Use `refactor` when the code *works* but needs structural improvement.
+
+## Workflow Overview
+
+```
+                              debug
+                                 │
+                            ┌────┴────┐
+                            │ Triage  │
+                            └────┬────┘
+                                 │
+               ┌─────────────────┼─────────────────┐
+               │                 │                 │
+          --hotfix            (default)       --escalate
+               │                 │                 │
+               ▼                 ▼                 ▼
+      ┌────────────────┐  ┌─────────────┐   ┌──────────┐
+      │  Hotfix Track  │  │   Thorough  │   │ ideate  │
+      │                │  │    Track    │   │ handoff  │
+      └────────────────┘  └─────────────┘   └──────────┘
+```
+
+## Command Interface
+
+### Start Debug Workflow
+
+```bash
+# Default: thorough track
+debug "Description of the bug"
+
+# Fast path: hotfix track
+debug --hotfix "Production is down - users can't login"
+
+# Escalate to feature workflow
+debug --escalate "This needs architectural changes"
+```
+
+### Mid-Workflow Commands
+
+```bash
+# Switch from hotfix to thorough (during investigation)
+debug --switch-thorough
+
+# Escalate to ideate (manual handoff)
+debug --escalate "Reason for escalation"
+
+# Resume after context compaction
+rehydrate
+```
+
+## Track Comparison
+
+| Aspect | Hotfix | Thorough |
+|--------|--------|----------|
+| Urgency | P0 (production down) | P1/P2 (normal priority) |
+| Investigation | 15 min time-boxed | No time limit |
+| RCA Document | No (minimal in state) | Yes (full docs/rca/) |
+| Worktree | No (in-place fix) | Yes (isolated) |
+| Review | Smoke test only | Spec review |
+| Human Checkpoints | 1 (merge) | 1 (merge) |
+
+### Decision Runbooks
+
+For track-selection criteria at the triage phase, query the decision runbook:
+`exarchos_orchestrate({ action: "runbook", id: "triage-decision" })`
+
+For investigation escalation criteria, query:
+`exarchos_orchestrate({ action: "runbook", id: "investigation-decision" })`
+
+These runbooks encode the structured decision trees for track selection. The agent reads the decision tree and follows the guidance — the platform does not execute branches.
+
+## Hotfix Track
+
+Fix production issues ASAP. Speed over ceremony.
+
+**HSM phases:** `triage` → `investigate` (15 min max) → `hotfix-implement` (no worktree) → `hotfix-validate` → `completed`
+
+See `references/triage-questions.md` for triage guidance.
+
+### Investigation Timer
+
+1. On hotfix track selection: record `investigation.startedAt` in state
+2. After each major finding: check elapsed time
+3. At 15 min mark: emit `investigation.timeout` event, pause for user confirmation
+   - Switch to thorough track? (yes/no)
+
+For detailed phase instructions, see `references/hotfix-track.md`.
+
+## Thorough Track
+
+Fix bugs with proper rigor. Full RCA documentation.
+
+**HSM phases:** `triage` → `investigate` → `rca` → `design` → `debug-implement` (worktree + TDD) → `debug-validate` → `debug-review` → `synthesize` → `completed`
+
+For detailed phase instructions, see `references/thorough-track.md`. For systematic investigation methodology, see `references/investigation-checklist.md`.
+
+### Characterization Testing (Thorough Track Only)
+
+Before fixing a bug in the thorough track, capture the buggy behavior as a characterization test:
+
+1. **Before fix:** Write a test that documents the current (buggy) behavior — it should PASS with the bug present
+2. **Write the fix test:** Write a test that describes the correct behavior — it should FAIL (this is the standard TDD RED phase)
+3. **Apply the fix:** Implement the fix. The fix test should now PASS, and the characterization test should now FAIL
+4. **Verify:** The characterization test failing confirms the bug is actually fixed. If it still passes, the fix didn't address the root cause.
+
+This is not required for the hotfix track — hotfixes prioritize speed over documentation.
+
+### Track Switching
+
+- **Hotfix -> Thorough:** When investigation timer expires (15 min). All findings preserved.
+- **Thorough -> Escalate:** When fix requires architectural changes. Hand off to `ideate`.
+
+For detailed switching logic, see `references/thorough-track.md`.
+
+## Auto-Chain Behavior
+
+Both tracks have ONE human checkpoint before completion.
+
+**Hotfix auto-chain:**
+```
+triage → investigate → hotfix-implement → [HUMAN: hotfix-validate] → completed
+         (auto)        (auto)
+```
+
+**Thorough auto-chain:**
+```
+triage → investigate → rca → design → debug-implement → debug-validate → debug-review → [HUMAN: synthesize] → completed
+         (auto)        (auto) (auto)   (auto)           (auto)            (auto)
+```
+
+## State Management
+
+Initialize debug workflow:
+```
+action: "init", featureId: "debug-<issue-slug>", workflowType: "debug"
+```
+
+See `@skills/debug/references/state-schema.md` for full schema.
+
+### Phase Transitions and Guards
+
+Every phase transition has a guard that must be satisfied. Before transitioning, consult `@skills/workflow-state/references/phase-transitions.md` for the exact prerequisite for each guard.
+
+### Schema Discovery
+
+Use `exarchos_workflow({ action: "describe", actions: ["set", "init"] })` for
+parameter schemas and `exarchos_workflow({ action: "describe", playbook: "debug" })`
+for phase transitions, guards, and playbook guidance.
+
+## Integration Points
+
+### With rehydrate
+
+Debug workflows resume like feature workflows:
+```bash
+rehydrate
+```
+
+### With Existing Skills
+
+- Uses spec-review skill for thorough track review phase
+- Uses synthesis skill for PR creation
+- Uses git-worktrees skill for thorough track implementation
+
+### With MCP Workflow State Tools
+
+Extended to support:
+- `workflowType: "debug"` field
+- Debug-specific phases handled by the SessionStart hook (which determines next action on resume)
+- Debug context provided by the SessionStart hook on session start
+
+## Completion Criteria
+
+### Hotfix Complete
+
+- [ ] Root cause identified (even if briefly)
+- [ ] Minimal fix applied
+- [ ] Affected tests pass
+- [ ] Follow-up RCA task created
+- [ ] Changes merged
+
+**Completion guard shapes** — set these via `exarchos_workflow set` before transitioning to `completed`:
+
+| Exit path | Guard | Required state |
+|-----------|-------|----------------|
+| Direct push (no PR) | `fix-verified-directly` | `resolution: { directPush: true, commitSha: "<sha>" }` |
+| Validation passed | `validation-passed` | `validation: { passed: true }` |
+| Via PR | Through `synthesize` → `completed` | `prUrl` must exist |
+
+### Thorough Complete
+
+- [ ] Full RCA documented in docs/rca/ (use `references/rca-template.md`)
+- [ ] Fix matches RCA findings
+- [ ] TDD implementation with tests
+- [ ] Spec review passed
+- [ ] PR merged
+
+**Completion guard shapes** — the thorough track exits through `synthesize` → `completed` (guard: `pr-url-exists`, requires `prUrl` in state).
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Start coding before understanding bug | Investigate first, always |
+| Skip RCA on thorough track | Document for future learning |
+| Exceed 15 min on hotfix investigation | Switch to thorough track |
+| Add features during bug fix | Scope creep - only fix the bug |
+| Skip tests because "it's just a fix" | Fixes need tests to prevent regression |
+
+## Troubleshooting
+
+See `references/troubleshooting.md` for MCP tool failures, state desync, investigation timeouts, and track switching issues.

package/skills/codex/debug/references/hotfix-track.md

@@ -0,0 +1,105 @@
+---
+name: hotfix-track
+---
+
+# Hotfix Track
+
+## Purpose
+
+Fix production issues or critical regressions ASAP. Speed over ceremony.
+
+## Phases
+
+```
+triage -> investigate -> hotfix-implement -> hotfix-validate -> completed
+  |          |            |                   |                  |
+  |          |            |                   |                  +- Human checkpoint: merge
+  |          |            |                   +- Smoke tests only
+  |          |            +- Minimal fix, no worktree
+  |          +- 15 min max, focused on root cause
+  +- Capture symptom, select track
+```
+
+## Phase Details
+
+### 1. Triage Phase
+
+Use `@skills/debug/references/triage-questions.md` to gather:
+- Symptom description
+- Reproduction steps
+- Urgency justification
+- Affected area
+
+Run deterministic track selection:
+
+```typescript
+exarchos_orchestrate({
+  action: "select_debug_track",
+  urgency: "<critical|high|medium|low>",
+  rootCauseKnown: "<yes|no>"
+})
+```
+
+**On `passed: true`:** Hotfix track selected.
+**On `passed: false`:** Thorough track selected.
+
+**Save triage results and advance to investigate:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "debug" })` for the `triage → investigate` guard requirements, then `set` the required fields (triage, urgency, track) and phase.
+
+### 2. Investigate Phase (15 min max)
+
+Use `@skills/debug/references/investigation-checklist.md`.
+
+Run the investigation timer to enforce the 15-minute time-box:
+
+```typescript
+exarchos_orchestrate({
+  action: "investigation_timer",
+  stateFile: "<state-file>"
+})
+```
+
+**On `passed: true`:** Within budget -- continue investigation.
+**On `passed: false`:** Budget exceeded -- escalate to thorough track.
+
+**Record findings and advance when root cause found:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "debug" })` for the `investigate → hotfix-implement` guard requirements and the expected field shapes for investigation findings, then `set` accordingly.
+
+### 3. Implement Phase
+
+Apply minimal fix directly (no worktree):
+- Change only what's necessary
+- No new features or refactoring
+- Record fix approach in state
+
+Call `exarchos_workflow({ action: "describe", playbook: "debug" })` for the `hotfix-implement → hotfix-validate` guard requirements, then `set` the required fields (artifacts) and phase.
+
+### 4. Validate Phase
+
+Run affected tests only:
+```bash
+npm run test:run -- <affected-test-files>
+```
+
+If tests pass, call `exarchos_workflow({ action: "describe", playbook: "debug" })` for the `hotfix-validate → completed` guard requirements, then `set` the required fields (followUp) and phase.
+
+Create follow-up task for proper RCA:
+```bash
+cat > docs/follow-ups/$(date +%Y-%m-%d)-<issue-slug>.json << EOF
+{
+  "type": "follow-up",
+  "created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "source": "hotfix:<state-file>",
+  "task": "Create proper RCA for hotfix: <issue-slug>",
+  "context": {
+    "symptom": "<symptom>",
+    "quickFix": "<fix description>",
+    "affectedFiles": ["<files>"]
+  }
+}
+EOF
+```
+
+**Human checkpoint:** Confirm merge.

package/skills/codex/debug/references/investigation-checklist.md

@@ -0,0 +1,217 @@
+# Investigation Checklist
+
+Systematic approach to finding root cause during the investigate phase.
+
+## Investigation Process
+
+### Step 1: Reproduce the Issue
+
+Before investigating, ensure you can trigger the bug:
+
+```bash
+# Run the reproduction steps
+# Observe the failure
+# Capture any error output (redact secrets/PII before sharing)
+```
+
+**If cannot reproduce:**
+- Check environment differences (local vs prod)
+- Check data differences (test vs real data)
+- Check timing/race conditions
+- Ask for more context from reporter
+
+### Step 2: Identify Entry Point
+
+Find where the problem manifests:
+
+| Entry Point Type | How to Find |
+|-----------------|-------------|
+| Error message | Search codebase for exact text |
+| Failing test | Read test output for assertion location |
+| User report | Trace from UI component to backend |
+| Log entry | Search logs for timestamp, correlate with code |
+
+**Tools:**
+```bash
+# Search for error message
+Grep({ pattern: "exact error text", output_mode: "content" })
+
+# Find related files
+Glob({ pattern: "**/auth/**/*.ts" })
+
+# Read suspicious file
+Read({ file_path: "/path/to/file.ts" })
+```
+
+### Step 3: Trace Execution Path
+
+Follow the code from entry point to failure:
+
+1. **Identify the call stack** - What functions are called?
+2. **Check input values** - Are parameters valid?
+3. **Trace data flow** - Where does data transform?
+4. **Find the divergence** - Where does actual != expected?
+
+**Tracing Pattern:**
+```text
+Entry Point → Function A → Function B → [FAILURE POINT] → Function C (never reached)
+```
+
+### Step 4: Narrow Down Location
+
+Use binary search to isolate the problem:
+
+1. Add logging/breakpoints at midpoint
+2. Determine which half contains bug
+3. Repeat until isolated to specific lines
+
+**Quick Logging:**
+```typescript
+console.log('[DEBUG] checkpoint 1:', { value });
+console.log('[DEBUG] checkpoint 2:', { transformed });
+console.log('[DEBUG] checkpoint 3:', { result });
+```
+
+### Step 5: Understand the Why
+
+Once located, understand the mechanism:
+
+- **What condition fails?** (if/else, validation, null check)
+- **Why is that condition triggered?** (bad input, state corruption, race)
+- **When was this introduced?** (recent change, always broken, regression)
+
+## Hotfix Time-Boxing (15 Minutes)
+
+For hotfix track, investigation is time-boxed:
+
+```text
+0:00  - Start investigation
+0:05  - Should have identified entry point
+0:10  - Should have narrowed to general area
+0:15  - DECISION POINT
+       │
+       ├─ Root cause found → Transition to `hotfix-implement` (set track = "hotfix")
+       │
+       └─ Root cause NOT found → Transition to `rca` (set track = "thorough")
+```
+
+### 15-Minute Checkpoint Questions
+
+At 15 minutes, ask:
+1. Do I know the exact cause?
+2. Do I know exactly what code to change?
+3. Am I confident the fix won't break other things?
+
+If any answer is "no" → transition to `rca` (set `track = "thorough"`).
+
+### Switching to Thorough Track
+
+**Switch track and record findings:**
+
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "track": "thorough",
+  "investigation.findings": ["Investigated for 15 min, narrowed to auth module but root cause unclear"]
+}
+```
+
+## Investigation Tools
+
+### For Code Search
+
+```typescript
+// Find error message source
+Grep({ pattern: "Error: something failed", output_mode: "content" })
+
+// Find function definition
+Grep({ pattern: "function handleLogin", output_mode: "content" })
+
+// Find all usages
+Grep({ pattern: "handleLogin\\(", output_mode: "files_with_matches" })
+```
+
+### For Codebase Exploration
+
+```typescript
+// Use Explore agent for complex investigation
+Task({
+  subagent_type: "Explore",
+  description: "Find auth error handling",
+  prompt: "Find where authentication errors are handled and what could cause a 500 response"
+})
+```
+
+### For Test Execution
+
+```bash
+# Run specific test to see failure
+npm run test:run -- --grep "login"
+
+# Run tests with verbose output
+npm run test:run -- --reporter=verbose
+
+# Run tests in specific file
+npm run test:run -- src/auth/login.test.ts
+```
+
+### For Git History
+
+```bash
+# Find when file was last changed
+git log --oneline -10 -- src/auth/login.ts
+
+# Find what changed recently
+git diff HEAD~5 -- src/auth/
+
+# Blame specific lines
+git blame -L 50,60 src/auth/login.ts
+```
+
+## Recording Findings
+
+**Add finding:**
+
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "investigation.findings": ["Error occurs in handleLogin when session is null"]
+}
+```
+
+**Record root cause:**
+
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "investigation.rootCause": "Session cookie not being set due to SameSite attribute mismatch"
+}
+```
+
+**Mark investigation complete:**
+
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "investigation.completedAt": "2026-01-27T10:30:00Z"
+}
+```
+
+## Common Bug Patterns
+
+Quick reference for common root causes:
+
+| Symptom | Common Causes |
+|---------|---------------|
+| Null/undefined error | Missing null check, async race, optional field |
+| Type error | Wrong cast, schema mismatch, serialization issue |
+| Timeout | N+1 query, missing index, external service slow |
+| 500 error | Unhandled exception, missing env var, DB connection |
+| Wrong data | Cache stale, transaction isolation, merge conflict |
+| UI not updating | State not propagated, missing re-render, stale closure |
+
+## Escalation Triggers
+
+During investigation, escalate to `/exarchos:ideate` if you discover:
+
+- [ ] Fundamental design flaw requiring architectural change
+- [ ] Multiple interconnected bugs requiring coordinated fix
+- [ ] Security vulnerability requiring careful handling
+- [ ] Data corruption requiring recovery strategy
+- [ ] Issue affecting multiple teams/services