kata-doctor

Run diagnostic health checks on a Kata project and fix detected issues.

Health Checks:

1. Roadmap format migration — Detects old-format ROADMAP.md and migrates to current format
2. Phase directory collision detection — Detects duplicate numeric prefixes and migrates to globally sequential numbering

When invoked directly by user: run interactively with confirmation prompts. When invoked by other skills (auto mode): format migration proceeds automatically, collision fix reports the problem and suggests /kata-doctor for interactive resolution.

<execution_context> @./references/roadmap-format-spec.md </execution_context>

Mode: $ARGUMENTS (optional: --auto for non-interactive mode)

@.planning/ROADMAP.md @.planning/STATE.md

Parse arguments for mode:

AUTO_MODE=false
if echo "$ARGUMENTS" | grep -q "\-\-auto"; then
  AUTO_MODE=true
fi

Display diagnostic banner:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata ► PROJECT HEALTH CHECK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Running diagnostics...

Check 1: Roadmap Format

Run format detection:

node scripts/kata-lib.cjs check-roadmap 2>/dev/null
FORMAT_EXIT=$?

Exit code handling:

• 0 = Current format, skip migration
• 1 = Old format, needs migration
• 2 = No ROADMAP.md, skip check

If exit code 0:

✓ ROADMAP.md format: current

Continue to Check 2.

If exit code 2:

— ROADMAP.md: not found (skipped)

Continue to Check 2.

If exit code 1:

⚠ ROADMAP.md format: old (needs migration)

Proceed to roadmap migration.

Only runs if format check returned exit code 1.

Step 1: Parse old-format ROADMAP.md

Read the existing ROADMAP.md and extract:

• Project name (from # Roadmap: or # heading)
• All phases with their numbers, names, status, plan counts
• Any milestone version references
• Phase completion dates if present

cat .planning/ROADMAP.md

Step 2: Detect milestone boundaries

Analyze phases to group them by milestone. Look for:

• Version references in phase goals or headers
• <details> blocks (already partially migrated)
• Completed vs in-progress phases

Step 3: Build current-format structure

Transform to canonical format per roadmap-format-spec.md:

1. Add ## Milestones overview section with status icons
2. Wrap completed milestone phases in <details> blocks
3. Add ## Current Milestone: heading for active work
4. Preserve all phase details and content

Step 4: Write migrated ROADMAP.md

Use Write tool to update .planning/ROADMAP.md with new format.

Step 5: Verify migration

node scripts/kata-lib.cjs check-roadmap 2>/dev/null
VERIFY_EXIT=$?

If exit code 0:

✓ ROADMAP.md migrated to current format

If still exit code 1:

✗ ROADMAP.md migration failed - manual review needed

Display the file for user review.

Step 6: Commit (if enabled)

COMMIT_PLANNING_DOCS=$(node scripts/kata-lib.cjs read-config "commit_docs" "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false

If COMMIT_PLANNING_DOCS=true:

git add .planning/ROADMAP.md
git commit -m "docs: migrate ROADMAP.md to current format"

Check 2: Phase Directory Collisions

Scan for duplicate numeric prefixes across all phase state directories:

DUPES=$(for state in active pending completed; do
  ls .planning/phases/${state}/ 2>/dev/null
done | grep -oE '^[0-9]+' | sort -n | uniq -d)

# Also check flat directories (unmigrated projects)
FLAT_DUPES=$(ls .planning/phases/ 2>/dev/null | grep -E '^[0-9]' | grep -oE '^[0-9]+' | sort -n | uniq -d)

ALL_DUPES=$(echo -e "${DUPES}\n${FLAT_DUPES}" | sort -nu | grep -v '^$')

If no duplicates:

✓ Phase directories: no collisions

Continue to completion.

If duplicates found:

⚠ Phase directories: collisions detected
  Duplicate prefixes: [list]

If AUTO_MODE=true:

Collision fix requires user confirmation.
Run `/kata-doctor` interactively to resolve.

Exit without fixing.

If AUTO_MODE=false:

Proceed to collision migration.

Only runs if collisions detected AND AUTO_MODE=false.

This step incorporates the full logic from kata-migrate-phases:

Step 1: Validate environment

[ -f .planning/ROADMAP.md ] || { echo "ERROR: No ROADMAP.md found."; exit 1; }
[ -f .planning/STATE.md ] || { echo "ERROR: No STATE.md found."; exit 1; }

Step 2: Build milestone chronology

Parse ROADMAP.md to build globally sequential phase numbering:

GLOBAL_SEQ=0
CHRONOLOGY=""

while IFS= read -r line; do
  name=$(echo "$line" | grep -oE 'Phase [0-9.]+: .+' | sed 's/Phase [0-9.]*: //' | sed 's/\*\*$//' | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')
  if [ -n "$name" ]; then
    CHRONOLOGY="${CHRONOLOGY}${GLOBAL_SEQ} ${name}\n"
    GLOBAL_SEQ=$((GLOBAL_SEQ + 1))
  fi
done < <(grep -E 'Phase [0-9.]+:' .planning/ROADMAP.md)

Display: Chronology ([N] phases): 00 → foundation, 01 → api-endpoints, ...

Step 3: Map directories to phases

For each chronology entry, find matching directory across all states. Build mapping: STATE/OLD_DIR → STATE/NEW_PREFIX-SLUG

Step 4: Present migration plan

Migration Plan:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  completed/01-foundation      → completed/00-foundation
  completed/02-api-endpoints   → completed/01-api-endpoints
  completed/01-setup           → completed/02-setup
  ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total: [N] directories to rename

Use AskUserQuestion:

• header: "Migration"
• question: "Rename [N] directories to globally sequential numbers?"
• options:
  • "Proceed" — Execute all renames
  • "Cancel" — Abort migration

If cancelled: exit with "Migration cancelled."

Step 5: Execute two-pass rename

Pass 1: Rename all directories to temporary names: mv OLD tmp-{seq}-{slug}

Pass 2: Rename from temporary to final: mv tmp-{seq}-{slug} {padded}-{slug}

For active/pending phases, also rename internal files (*-PLAN.md, *-RESEARCH.md, etc.).

Step 6: Update documentation

Update ROADMAP.md current milestone phase numbers. Update STATE.md current position. Leave historical <details> blocks unchanged.

Step 7: Verify

Re-run collision detection:

DUPES=$(for state in active pending completed; do
  ls .planning/phases/${state}/ 2>/dev/null
done | grep -oE '^[0-9]+' | sort -n | uniq -d)

If clean:

✓ Phase directories migrated to globally sequential numbers
✓ No duplicate prefixes remain

Step 8: Commit

COMMIT_PLANNING_DOCS=$(node scripts/kata-lib.cjs read-config "commit_docs" "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false

If COMMIT_PLANNING_DOCS=true:

git add .planning/phases/ .planning/ROADMAP.md .planning/STATE.md
git commit -m "chore: migrate phase directories to globally sequential numbering"

Completion

Display completion summary:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata ► HEALTH CHECK COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[List each check with status]

✓ ROADMAP.md format: [current | migrated | not found]
✓ Phase directories: [no collisions | migrated | skipped]

If any migrations were performed:

Changes committed. Run `/kata-track-progress` to continue.

<anti_patterns>

• Don't modify historical <details> blocks content (only add if missing)
• Don't rename completed phase internal files during collision fix
• Don't run collision fix in auto mode without user confirmation
• Don't fail the entire health check if one check has issues </anti_patterns>

<success_criteria>

• Roadmap format detected correctly (current/old/missing)
• Old-format roadmaps migrated to current format
• Migrated format verified with check script
• Phase collisions detected across all state directories
• Collision migration uses two-pass rename (no mid-rename collisions)
• Documentation updated after collision migration
• Changes committed (if commit_docs enabled)
• Auto mode skips collision fix with informative message
• User informed of all check results </success_criteria>