@lvlup-sw/exarchos 2.5.0 → 2.6.0

package/skills/generic/debug/references/rca-template.md

@@ -0,0 +1,150 @@
+# RCA Template
+
+Use this template when documenting root cause analysis for bugs.
+
+## Template
+
+```markdown
+# RCA: [Issue Title]
+
+## Summary
+
+[1-2 sentences: What broke and why]
+
+## Symptom
+
+[How the bug manifested - error messages, behavior, user reports]
+
+### Reproduction Steps
+
+1. [Step 1]
+2. [Step 2]
+3. [Step N]
+
+### Observed Behavior
+
+[What happened]
+
+### Expected Behavior
+
+[What should have happened]
+
+## Root Cause
+
+[Technical explanation of why this happened]
+
+### Code Location
+
+File: `[path/to/file.ts]`
+Line: [N]
+
+### Analysis
+
+[Detailed technical analysis of the bug mechanism]
+
+## Contributing Factors
+
+[What conditions allowed this bug to exist/ship]
+
+- [ ] Missing test coverage
+- [ ] Inadequate code review
+- [ ] Unclear requirements
+- [ ] Race condition / timing issue
+- [ ] Edge case not considered
+- [ ] External dependency failure
+- [ ] Configuration error
+- [ ] Other: [describe]
+
+## Fix Approach
+
+[High-level approach to fixing - not full implementation details]
+
+### Changes Required
+
+| File | Change |
+|------|--------|
+| `path/to/file.ts` | [Brief description] |
+
+### Risks
+
+[Any risks introduced by the fix]
+
+## Prevention
+
+[How to prevent similar issues in future]
+
+### Immediate Actions
+
+- [ ] [Action 1]
+- [ ] [Action 2]
+
+### Long-term Improvements
+
+- [ ] [Improvement 1]
+- [ ] [Improvement 2]
+
+## Timeline
+
+| Event | Date | Notes |
+|-------|------|-------|
+| Reported | YYYY-MM-DD | [How it was reported] |
+| Investigated | YYYY-MM-DD | [Time spent] |
+| Fixed | YYYY-MM-DD | [PR/commit reference] |
+| Verified | YYYY-MM-DD | [How verified in production] |
+
+## Related
+
+- Issue: [link or N/A]
+- PR: [link or N/A]
+- Related RCAs: [links or N/A]
+```
+
+## Usage
+
+1. Copy template to `docs/rca/YYYY-MM-DD-<issue-slug>.md`
+2. Fill in all sections during investigation
+3. Update timeline as work progresses
+4. Link to PR when fix is merged
+
+## Naming Convention
+
+`YYYY-MM-DD-<issue-slug>.md`
+
+Examples:
+- `2026-01-27-null-user-session.md`
+- `2026-01-27-api-timeout-on-large-payload.md`
+- `2026-01-27-login-redirect-loop.md`
+
+## Abbreviated Template (Hotfix Follow-up)
+
+For RCAs created after a hotfix, use this abbreviated version:
+
+```markdown
+# RCA: [Issue Title]
+
+## Summary
+
+[What broke and the quick fix applied]
+
+## Hotfix Reference
+
+- State file: `~/.claude/workflow-state/debug-<issue>.state.json`
+- Commit: [hash]
+- Date: YYYY-MM-DD
+
+## Root Cause
+
+[Now that you have time, document the actual root cause]
+
+## Why Hotfix Worked
+
+[Explain why the quick fix resolved the symptom]
+
+## Proper Fix (if needed)
+
+[If the hotfix was not the ideal solution, document what should be done]
+
+## Prevention
+
+[How to prevent similar issues]
+```

package/skills/generic/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/generic/debug/references/thorough-track.md

@@ -0,0 +1,171 @@
+---
+name: thorough-track
+---
+
+# Thorough Track
+
+## Purpose
+
+Fix bugs with proper rigor. Capture institutional knowledge through RCA.
+
+## Phases
+
+```
+triage -> investigate -> rca -> design -> debug-implement -> debug-validate -> debug-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:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "debug" })` for the `triage → investigate` guard requirements, then `set` the track to `"thorough"` and phase.
+
+### 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:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "debug" })` for the `rca → design` guard requirements, then `set` the required fields (artifacts.rca) and phase.
+
+### 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:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "debug" })` for the `design → debug-implement` guard requirements, then `set` the required fields (artifacts.fixDesign) and phase.
+
+### 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 validate:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "debug" })` for the `debug-implement → debug-validate` guard requirements, then `set` the required fields (worktrees) and phase.
+
+### 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:
+
+```typescript
+exarchos_orchestrate({
+  action: "debug_review_gate",
+  repoRoot: "<path>",
+  baseBranch: "<branch>"
+})
+```
+
+**On `passed: true`:** Review passed -- tests added and passing.
+**On `passed: false`:** Gaps found -- missing tests or regressions.
+
+Additionally verify:
+- [ ] Fix matches RCA root cause
+- [ ] Fix matches design approach
+
+Update state:
+
+**Advance to synthesize:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "debug" })` for the `debug-review → synthesize` guard requirements, then `set` the phase.
+
+### 7. Synthesize Phase
+
+Create PR via GitHub CLI:
+
+```bash
+# Stage, commit, and push
+git add <fixed-files>
+git commit -m "fix: <issue summary>"
+git push -u origin <branch-name>
+
+# Create PR and enable auto-merge
+gh pr create --base main --title "fix: <issue summary>" --body "<pr-body>"
+gh pr merge <number> --auto --squash
+```
+
+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 `exarchos_orchestrate({ action: "investigation_timer" })` returns `passed: false` (budget exceeded), switch to thorough track:
+
+**Switch to thorough track:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "debug" })` for the field shapes, then `set` the track to `"thorough"` and record the switch reason in `investigation.findings`.
+
+Continue investigation without time constraint.
+
+### Thorough -> Escalate
+
+If fix requires architectural changes:
+
+**Escalate to blocked:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "debug" })` for the guard requirements, then `set` the investigation findings and phase to `"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>`