Auto-Skiller Check if --repair or --backfill flags are present in the command arguments.
REPAIR_FLAG=""
BACKFILL_FLAG=""
if arguments contain "--repair"; then
REPAIR_FLAG="--repair"
fi
if arguments contain "--backfill"; then
BACKFILL_FLAG="--backfill"
fi
gsd-sdk query validate.health $REPAIR_FLAG $BACKFILL_FLAG
Parse JSON output:
status: "healthy" | "degraded" | "broken"errors[]: Critical issues (code, message, fix, repairable)warnings[]: Non-critical issuesinfo[]: Informational notesrepairable_count: Number of auto-fixable issuesrepairs_performed[]: Actions taken if --repair was used
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD Health Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: HEALTHY | DEGRADED | BROKEN
Errors: N | Warnings: N | Info: N
If repairs were performed:
## Repairs Performed
- ✓ config.json: Created with defaults
- ✓ STATE.md: Regenerated from roadmap
If errors exist:
## Errors
- [E001] config.json: JSON parse error at line 5
Fix: Run /gsd-health --repair to reset to defaults
- [E002] PROJECT.md not found
Fix: Run /gsd-new-project to create
If warnings exist:
## Warnings
- [W002] STATE.md references phase 5, but only phases 1-3 exist
Fix: Review STATE.md manually before changing it; repair will not overwrite an existing STATE.md
- [W005] Phase directory "1-setup" doesn't follow NN-name format
Fix: Rename to match pattern (e.g., 01-setup)
If info exists:
## Info
- [I001] 02-implementation/02-01-PLAN.md has no SUMMARY.md
Note: May be in progress
Footer (if repairable issues exist and --repair was NOT used):
---
N issues can be auto-repaired. Run: /gsd-health --repair
Ask user if they want to run repairs:
Would you like to run /gsd-health --repair to fix N issues automatically?
If yes, re-run with --repair flag and display results.
Re-run health check without --repair to confirm issues are resolved:
gsd-sdk query validate.health
Report final status.
| Code | Severity | Description | Repairable |
|---|---|---|---|
| E001 | error | .planning/ directory not found | No |
| E002 | error | PROJECT.md not found | No |
| E003 | error | ROADMAP.md not found | No |
| E004 | error | STATE.md not found | Yes |
| E005 | error | config.json parse error | Yes |
| W001 | warning | PROJECT.md missing required section | No |
| W002 | warning | STATE.md references invalid phase | No |
| W003 | warning | config.json not found | Yes |
| W004 | warning | config.json invalid field value | No |
| W005 | warning | Phase directory naming mismatch | No |
| W006 | warning | Phase in ROADMAP but no directory | No |
| W007 | warning | Phase on disk but not in ROADMAP | No |
| W008 | warning | config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip) | Yes |
| W009 | warning | Phase has Validation Architecture in RESEARCH.md but no VALIDATION.md | No |
| W018 | warning | MILESTONES.md missing entry for archived milestone snapshot | Yes (--backfill) |
| W019 | warning | Unrecognized .planning/ root file — not a canonical GSD artifact | No |
| I001 | info | Plan without SUMMARY (may be in progress) | No |
| Action | Effect | Risk |
|---|---|---|
| createConfig | Create config.json with defaults | None |
| resetConfig | Delete + recreate config.json | Loses custom settings |
| regenerateState | Create STATE.md from ROADMAP structure when it is missing | Loses session history |
| addNyquistKey | Add workflow.nyquist_validation: true to config.json | None — matches existing default |
| backfillMilestones | Synthesize missing MILESTONES.md entries from .planning/milestones/vX.Y-ROADMAP.md snapshots |
None — additive only; triggered by --backfill flag |
Not repairable (too risky):
- PROJECT.md, ROADMAP.md content
- Phase directory renaming
- Orphaned plan cleanup
When --repair is active, detect and clean up:
# Check for stale task directories (older than 24 hours)
TASKS_DIR="$HOME/.claude/tasks"
if [ -d "$TASKS_DIR" ]; then
STALE_COUNT=$( (find "$TASKS_DIR" -maxdepth 1 -type d -mtime +1 2>/dev/null || true) | wc -l )
if [ "$STALE_COUNT" -gt 0 ]; then
echo "⚠️ Found $STALE_COUNT stale task directories in ~/.claude/tasks/"
echo " These are leftover from crashed subagent sessions."
echo " Run: rm -rf ~/.claude/tasks/* (safe — only affects dead sessions)"
fi
fi
Report as info diagnostic: I002 | info | Stale subagent task directories found | Yes (--repair removes them)