debug

# /debug — Systematic Error Resolution

<context>
**User Input**: $ARGUMENTS

**Current Branch**: !`git branch --show-current 2>/dev/null || echo "none"`

**Feature Slug**: !`git branch --show-current 2>/dev/null | sed 's/^feature\///' || echo "unknown"`

**Recent Debug Sessions**: !`ls -1t specs/*/debug-session.json 2>/dev/null | head -3 || echo "none"`

**Recent Errors**: !`tail -20 specs/*/error-log.md 2>/dev/null | grep "^###" | head -3 || echo "none"`

**Git Status**: !`git status --short 2>/dev/null || echo "clean"`

**Debug Session Artifacts** (after script execution):
- @specs/*/debug-session.json
- @specs/*/debug/run-XXXXXX/*.log
- @specs/*/error-log.md
</context>

<objective>
Systematically debug errors using spec-cli.py, track failures in error-log.md, and generate machine-readable session reports.

Execute debugging workflow by:
1. Running centralized debug script with arguments: $ARGUMENTS
2. Analyzing verification status (lint, types, tests)
3. Reading log files if verification failed
4. Presenting results with actionable next steps
5. Updating error knowledge base (error-log.md)

**Modes**:
- **Manual**: User specifies error type and component (non-interactive by default)
- **Structured**: Auto-invoked by `/optimize` with issue metadata (--from-optimize)

**Philosophy**: Every error is a learning opportunity. Document failures, symptoms, root causes, and fixes. The error-log.md becomes the project's debugging knowledge base.

**Workflow position**: `implement → debug → optimize → preview → ship`
</objective>

## Anti-Hallucination Rules

**CRITICAL**: Follow these rules to prevent fabricating debug results.

1. **Never claim script success without reading artifacts**
   - Always Read debug-session.json to verify status
   - Quote actual verification result: "passed" or "failed"
   - Cite log files: "See specs/my-feature/debug/run-abc123/pytest.log:45"

2. **Always read log files if verification failed**
   - Don't guess at errors - read actual log content
   - Quote verbatim error messages with file:line references
   - Show stack traces or lint errors from logs

3. **Never invent fix recommendations**
   - If script provides recommendation, quote it exactly
   - If no recommendation, say "Manual investigation required"
   - Don't suggest fixes without analyzing actual error output

4. **Verify artifacts exist before claiming completion**
   - Check error-log.md was updated (read latest entry)
   - Confirm debug-session.json exists and is valid JSON
   - Verify log directory created: specs/*/debug/run-XXXXXX/

5. **Never assume git operations succeeded**
   - If --push flag used, verify with git log
   - Check git status after script to confirm commits
   - Quote actual commit message from git log

**Why this matters**: Fabricated debug results hide real issues. Accurate artifact reading ensures debugging sessions are reproducible and errors are properly documented.

---

<process>

### Step 0: Dry-Run Mode Detection

**Check for --dry-run flag** (see `.claude/skills/dry-run/SKILL.md`):

```bash
DRY_RUN="false"
if [[ "$ARGUMENTS" == *"--dry-run"* ]]; then
  DRY_RUN="true"
  ARGUMENTS=$(echo "$ARGUMENTS" | sed 's/--dry-run//g' | xargs)
  echo "DRY-RUN MODE ENABLED"
fi
```

**If DRY_RUN is true:**

Output dry-run summary and exit:

```
════════════════════════════════════════════════════════════════════════════════
DRY-RUN MODE: No changes will be made
════════════════════════════════════════════════════════════════════════════════

📋 COMMAND: /debug $ARGUMENTS

📋 CONTEXT THAT WOULD BE READ:
  • Current branch: $(git branch --show-current)
  • Feature slug: extracted from branch or argument
  • Recent debug sessions: specs/*/debug-session.json
  • Recent errors: specs/*/error-log.md

🔧 SCRIPT THAT WOULD EXECUTE:
  python .spec-flow/scripts/spec-cli.py debug "$ARGUMENTS"

  Script operations:
    1. Parse arguments (feature slug, flags, issue metadata)
    2. Load feature directory and validate existence
    3. Initialize error-log.md template if missing
    4. Show recent error log entries (context)
    5. Run verification (lint, types, tests based on --type/--component)
    6. Optional: Deployment diagnostics (if --deploy-diag)
    7. Aggregate verification summary
    8. Update error-log.md with timestamped entry
    9. Emit debug-session.json
    10. Commit artifacts if verification passed
    11. Display summary

📁 FILES THAT WOULD BE CREATED:
  ✚ specs/[slug]/debug-session.json (machine-readable session data)
  ✚ specs/[slug]/debug/run-XXXXXX/ (directory for this session)
  ✚ specs/[slug]/debug/run-XXXXXX/*.log (verification logs)

📝 FILES THAT WOULD BE MODIFIED:
  ✎ specs/[slug]/error-log.md
    + New entry: "### Entry N: YYYY-MM-DD HH:MM:SS UTC"
    + Symptoms, root cause, fix applied
    + Regression test reference (if generated)

🧪 REGRESSION TEST (if bug found):
  ✚ tests/regression/regression-ERR-XXXX-[slug].test.ts
    - Arrange-Act-Assert pattern
    - Linked to error-log.md entry

🔀 GIT OPERATIONS (if verification passes):
  • git add specs/[slug]/error-log.md specs/[slug]/debug-session.json
  • git commit -m "debug: session complete for [feature-slug]"
  • git push origin [branch] (if --push flag)

📊 EXIT CODES:
  • 0 = Verification passed, artifacts committed
  • 1 = Bad arguments or script error
  • 2 = Verification failed, artifacts created but not committed

════════════════════════════════════════════════════════════════════════════════
DRY-RUN COMPLETE: 0 actual changes made
Run `/debug $ARGUMENTS` (without --dry-run) to execute
════════════════════════════════════════════════════════════════════════════════
```

**Exit after dry-run summary. Do NOT proceed to script execution.**

---

### Step 1: Execute Debug Script

Run the centralized spec-cli tool with user arguments:

```bash
python .spec-flow/scripts/spec-cli.py debug "$ARGUMENTS"
```

**Script operations** (automated):
1. Parse arguments (feature slug, flags, issue metadata)
2. Load feat