@lvlup-sw/exarchos 2.0.1

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

@@ -0,0 +1,134 @@
+---
+name: hotfix-track
+---
+
+# Hotfix Track
+
+## Purpose
+
+Fix production issues or critical regressions ASAP. Speed over ceremony.
+
+## Phases
+
+```
+Triage -> Investigate -> Implement -> 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:
+
+```bash
+scripts/select-debug-track.sh --urgency <critical|high|medium|low> --root-cause-known <yes|no>
+```
+
+**On exit 0:** Hotfix track selected.
+**On exit 1:** Thorough track selected.
+
+**Save triage results and advance:**
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "triage": {
+    "symptom": "<symptom>",
+    "reproduction": "<steps>",
+    "affectedArea": "<area>",
+    "impact": "<impact>"
+  },
+  "urgency": {
+    "level": "<level>",
+    "justification": "<justification>"
+  },
+  "track": "hotfix"
+}, phase: "investigate"
+```
+
+### 2. Investigate Phase (15 min max)
+
+Use `@skills/debug/references/investigation-checklist.md`.
+
+Run the investigation timer to enforce the 15-minute time-box:
+
+```bash
+scripts/investigation-timer.sh --state-file <state-file>
+```
+
+**On exit 0:** Within budget -- continue investigation.
+**On exit 1:** Budget exceeded -- escalate to thorough track.
+
+**Record findings:**
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "investigation": { "findings": ["<finding>"] }
+}
+```
+
+**When root cause found:**
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "investigation": {
+    "rootCause": "<root cause>",
+    "completedAt": "<ISO8601>"
+  }
+}, phase: "implement"
+```
+
+### 3. Implement Phase
+
+Apply minimal fix directly (no worktree):
+- Change only what's necessary
+- No new features or refactoring
+- Record fix approach in state
+
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "artifacts": { "fixDesign": "<brief fix description>" }
+}, phase: "validate"
+```
+
+### 4. Validate Phase
+
+Run affected tests only:
+```bash
+npm run test:run -- <affected-test-files>
+```
+
+If tests pass:
+
+```
+action: "set", featureId: "debug-<issue-slug>", updates: {
+  "followUp": { "rcaRequired": true }
+}, phase: "completed"
+```
+
+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/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 → Continue to fix phase
+       │
+       └─ Root cause NOT found → Switch to thorough track
+```
+
+### 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" -> switch to thorough track.
+
+### 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

package/skills/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]
+```