Skip to main content

Lesson 9: Troubleshooting

Time: 25 minutes Goal: Diagnose and fix common issues

Quick Diagnosis​

When something isn't working:

# Step 1: Check status
/specweave:status

# Step 2: Validate structure
/specweave:validate 0001

# Step 3: Sync everything
/specweave:sync-progress

# Step 4: Check workflow
/specweave:workflow

Common Issues​

"No active increment found"​

Cause: No increment in progress.

Solution:

# Create new
/specweave:increment "Your feature"

# Or resume existing
/specweave:resume 0001

"WIP limit reached"​

Cause: Too many increments active.

Solution:

# Complete one
/specweave:done 0001

# Or pause one
/specweave:pause 0002

# Or override (with reason)
/specweave:increment "urgent-fix" --override-wip "Critical bug"

"Gate validation failed"​

Cause: Quality gate not passed.

Solution:

# Check what's missing
/specweave:validate 0001

# Complete missing work
/specweave:do --task T-005

# Or defer P2/P3 tasks
# In tasks.md:
# **Status**: [ ] deferred
# **Deferral Reason**: Scheduled for 0003

# Emergency bypass (rare!)
/specweave:done 0001 --force --reason "CVE fix"

"External sync failed"​

Cause: Token expired or rate limit.

Solution:

# Check status
/specweave-github:status

# If expired: regenerate token in .env
# GITHUB_TOKEN=ghp_newtoken

# Force re-sync
/specweave-github:sync 0001 --force

"AC-IDs not found"​

Cause: Tasks missing AC references.

Solution:

### T-003: Implement validation
**User Story**: US-001
**Satisfies ACs**: AC-US1-01, AC-US1-02  ← Add this line
**Status**: [ ] pending

"Hook not firing"​

Cause: Hook misconfigured.

Solution:

# Check hooks
/specweave:check-hooks

# Verify hooks.json exists
ls plugins/specweave/hooks/hooks.json

"Hook causing crashes"​

Emergency fix:

# Disable hooks
export SPECWEAVE_DISABLE_HOOKS=1

# Or rename file
mv plugins/specweave/hooks/hooks.json hooks.json.bak

# Clean state
rm -f .specweave/state/.hook-*

# Restart Claude Code

"YAML frontmatter invalid"​

Cause: Bad spec.md format.

Solution:

# spec.md must start with valid YAML
---
increment: 0001-feature-name
feature_id: FS-001
status: in-progress
---

# Content here...

Common errors:

# ❌ Wrong: Unquoted colon
increment: 0001-feature: name

# ✅ Correct: Quoted
increment: "0001-feature: name"

"Tests not detected"​

Cause: Test command not configured.

Solution: In .specweave/config.json:

{
  "testing": {
    "command": "npm test",
    "coverageCommand": "npm test -- --coverage"
  }
}

"Performance slow"​

Cause: Large context or multiple agents.

Solution:

# Pause complex increments
/specweave:pause 0001

# Use smaller model
"Using Haiku: find all TODO comments"

# Close completed work
/specweave:done 0001

Diagnostic Commands​

/specweave:status          # Overall status
/specweave:validate 0001   # Validate increment
/specweave:check-hooks     # Hook health
/specweave:sync-diagnostics # Sync issues
/specweave:workflow        # Current state

Recovery Procedures​

Corrupted Increment​

# Backup
cp -r .specweave/increments/0001 0001.bak

# Try fix
/specweave:validate 0001 --fix

# Or restore from git
git checkout HEAD -- .specweave/increments/0001/

Lost Progress​

# Check git history
git log --oneline .specweave/increments/0001/tasks.md

# Restore version
git checkout abc123 -- .specweave/increments/0001/tasks.md

Glossary Terms Used​

  • Increment — A unit of work
  • WIP Limits — Work-in-progress constraints
  • Hooks — Automated scripts at lifecycle events

Key Takeaways​

IssueQuick Fix
No active increment/specweave:status → create or resume
WIP limitComplete or pause an increment
Gate failed/specweave:validate → fix issues
Sync broken/specweave:sync-progress --force
Hooks crashingexport SPECWEAVE_DISABLE_HOOKS=1

Golden rule: When stuck, run /specweave:workflow

What's Next?​

Master advanced patterns for complex projects.

:next → Lesson 10: Advanced Patterns