parade-doctor

name	parade-doctor
description	Diagnose and verify Parade project setup. Checks all required components and reports issues.

Parade Doctor Skill

Purpose

Diagnose and verify Parade project setup. Checks all required components (directories, database, beads integration, skills, configuration) and reports health status with actionable recommendations.

When to Use

• After running npx parade-init and /init-project
• When something isn't working correctly
• To verify project health before starting work
• When debugging workflow issues
• User explicitly invokes /parade-doctor

---

Diagnostic Checks

1. Directory Structure

• .parade/ exists
• .claude/ exists
• .beads/ exists
• project.yaml exists

2. Database Health

• discovery.db exists (check both .parade/ and root)
• Database is readable
• Required tables exist: briefs, specs, interview_questions, sme_reviews, workflow_events, agent_telemetry

3. Beads Integration

• bd CLI is installed and in PATH
• bd list works
• .beads/config.yaml exists and is valid

4. Skill Files

• discover/SKILL.md exists
• approve-spec/SKILL.md exists
• run-tasks/SKILL.md exists
• retro/SKILL.md exists
• workflow-status/SKILL.md exists
• init-project/SKILL.md exists

5. Configuration

• project.yaml is valid YAML
• Has required fields: project.name, stacks
• Optional fields: design_system, agents.custom

---

Execution Flow

Step 1: Check Directory Structure

# Check required directories
if [ -d ".parade" ]; then
  echo "✅ .parade/ directory"
else
  echo "❌ .parade/ directory missing"
fi

if [ -d ".claude" ]; then
  echo "✅ .claude/ directory"
else
  echo "❌ .claude/ directory missing"
fi

if [ -d ".beads" ]; then
  echo "✅ .beads/ directory"
else
  echo "❌ .beads/ directory missing"
fi

if [ -f "project.yaml" ]; then
  echo "✅ project.yaml"
else
  echo "❌ project.yaml missing"
fi

Step 2: Check Database Health

# Find discovery.db location
if [ -f ".parade/discovery.db" ]; then
  DISCOVERY_DB=".parade/discovery.db"
  echo "✅ discovery.db found at .parade/discovery.db"
elif [ -f "./discovery.db" ]; then
  DISCOVERY_DB="./discovery.db"
  echo "⚠️ discovery.db found at project root (legacy location)"
else
  echo "❌ discovery.db not found"
  DISCOVERY_DB=""
fi

# Test database readability
if [ -n "$DISCOVERY_DB" ]; then
  if sqlite3 "$DISCOVERY_DB" "SELECT 1;" >/dev/null 2>&1; then
    echo "✅ Database readable"
  else
    echo "❌ Database corrupted or unreadable"
  fi

  # Check required tables
  TABLES=$(sqlite3 "$DISCOVERY_DB" "SELECT name FROM sqlite_master WHERE type='table';")
  REQUIRED_TABLES=("briefs" "specs" "interview_questions" "sme_reviews" "workflow_events" "agent_telemetry")

  for table in "${REQUIRED_TABLES[@]}"; do
    if echo "$TABLES" | grep -q "^$table$"; then
      echo "✅ Table: $table"
    else
      echo "❌ Missing table: $table"
    fi
  done
fi

Step 3: Check Beads Integration

# Check bd CLI
if command -v bd >/dev/null 2>&1; then
  BD_VERSION=$(bd --version 2>&1 || echo "unknown")
  echo "✅ bd CLI installed (version $BD_VERSION)"

  # Test bd list
  if bd list --json >/dev/null 2>&1; then
    echo "✅ bd list works"
  else
    echo "❌ bd list failed"
  fi
else
  echo "❌ bd CLI not installed"
fi

# Check beads config
if [ -f ".beads/config.yaml" ]; then
  echo "✅ .beads/config.yaml exists"
  # Validate YAML
  if python3 -c "import yaml; yaml.safe_load(open('.beads/config.yaml'))" 2>/dev/null; then
    echo "✅ config.yaml valid"
  else
    echo "⚠️ config.yaml may have syntax issues"
  fi
else
  echo "❌ .beads/config.yaml missing"
fi

Step 4: Check Skill Files

SKILLS=("discover" "approve-spec" "run-tasks" "retro" "workflow-status" "init-project")

for skill in "${SKILLS[@]}"; do
  if [ -f ".claude/skills/$skill/SKILL.md" ]; then
    echo "✅ $skill"
  else
    echo "❌ Missing: $skill"
  fi
done

Step 5: Check Configuration

if [ -f "project.yaml" ]; then
  # Validate YAML syntax
  if python3 -c "import yaml; yaml.safe_load(open('project.yaml'))" 2>/dev/null; then
    echo "✅ project.yaml valid YAML"

    # Check required fields
    if grep -q "name:" project.yaml; then
      PROJECT_NAME=$(grep "name:" project.yaml | head -1 | sed 's/.*name: *//' | tr -d '"')
      echo "✅ Project name: $PROJECT_NAME"
    else
      echo "❌ Missing: project.name"
    fi

    if grep -q "stacks:" project.yaml; then
      echo "✅ stacks section defined"
    else
      echo "❌ Missing: stacks section"
    fi

    # Check optional fields
    if grep -q "design_system:" project.yaml; then
      echo "✅ design_system section defined"
    else
      echo "⚠️ Optional: design_system section (consider adding)"
    fi

    if grep -q "agents:" project.yaml && grep -q "custom:" project.yaml; then
      echo "✅ Custom agents defined"
    else
      echo "⚠️ Optional: custom agents (not required)"
    fi
  else
    echo "❌ project.yaml has syntax errors"
  fi
fi

---

Output Format

🏥 Parade Doctor - Project Health Check

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Directory Structure:
  ✅ .parade/ directory
  ✅ .claude/ directory
  ✅ .beads/ directory
  ✅ project.yaml

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Database:
  ✅ discovery.db found at .parade/discovery.db
  ✅ Database readable
  ✅ Table: briefs
  ✅ Table: specs
  ✅ Table: interview_questions
  ✅ Table: sme_reviews
  ✅ Table: workflow_events
  ✅ Table: agent_telemetry

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Beads CLI:
  ✅ bd CLI installed (version 0.5.2)
  ✅ bd list works
  ✅ .beads/config.yaml exists
  ✅ config.yaml valid

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Skills:
  ✅ discover
  ✅ approve-spec
  ✅ run-tasks
  ✅ retro
  ✅ workflow-status
  ✅ init-project

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Configuration:
  ✅ project.yaml valid YAML
  ✅ Project name: "MyProject"
  ✅ stacks section defined
  ⚠️ Optional: design_system section (consider adding)
  ⚠️ Optional: custom agents (not required)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Health Score: 95% (23/24 checks passed)

Recommendations:
  - Consider adding a design_system section to project.yaml
  - All critical components are healthy!

---

Error Output Examples

Missing .parade/ Directory

❌ .parade/ directory missing

How to fix:
1. Run: npx parade-init
2. Follow the setup wizard
3. Run: /parade-doctor again

Missing discovery.db

❌ discovery.db not found

How to fix:
1. Ensure you've run /init-project
2. Or manually create: sqlite3 .parade/discovery.db ".databases"
3. Run any workflow skill (/discover) to initialize schema

bd CLI Not Installed

❌ bd CLI not installed

How to fix:
1. Install beads: npm install -g @beadlabs/beads-cli
2. Or via brew: brew install beads-cli
3. Verify: bd --version

Missing Skill Files

❌ Missing: discover
❌ Missing: approve-spec

How to fix:
1. Re-run: npx parade-init --repair
2. Or manually copy from parade-init package:
   cp -r node_modules/@parade/init/.claude/skills/* .claude/skills/

Invalid project.yaml

❌ project.yaml has syntax errors

How to fix:
1. Validate YAML: cat project.yaml | python3 -c "import yaml, sys; yaml.safe_load(sys.stdin)"
2. Common issues: incorrect indentation, missing quotes
3. Re-run: /init-project to regenerate

---

Health Score Calculation

Total Checks:
- Directory Structure: 4 checks
- Database: 7 checks (1 location + 1 readable + 5 tables)
- Beads Integration: 4 checks
- Skills: 6 checks
- Configuration: 4 checks (2 required + 2 optional)

Score = (passed_checks / total_checks) * 100

Thresholds:
- 100%: Perfect health
- 90-99%: Good health (minor optional items missing)
- 70-89%: Degraded (some components missing)
- <70%: Critical (major components missing)

---

Implementation Notes

Shell Script vs. Direct Execution

Execute checks directly in bash for speed and reliability. Use Python only for YAML validation if available (graceful fallback if not).

Error Handling

• Use 2>/dev/null || true to silence expected errors
• Distinguish between "missing" vs "broken" components
• Provide specific, actionable error messages

Platform Compatibility

• Use POSIX-compliant bash commands
• Test on macOS, Linux, Windows (Git Bash)
• Gracefully handle missing utilities (python3, sqlite3)

Performance

All checks should complete in < 2 seconds. No network calls required.

---

Example Invocations

Healthy Project

User: /parade-doctor

Claude: Running health check...

🏥 Parade Doctor - Project Health Check

[All green checkmarks]

Health Score: 100% (28/28 checks passed)

Your Parade setup is perfect! Ready to start building.

Fresh Project (Missing beads)

User: /parade-doctor

Claude: Running health check...

🏥 Parade Doctor - Project Health Check

Directory Structure: ✅ (4/4)
Database: ✅ (7/7)
Beads CLI: ❌ (0/4)
  ❌ bd CLI not installed
Skills: ✅ (6/6)
Configuration: ✅ (4/4)

Health Score: 74% (21/28 checks passed)

Critical Issue:
  Beads CLI is not installed. Install with:
  npm install -g @beadlabs/beads-cli

After fixing, run /parade-doctor again.

---

Integration with Other Skills

/init-project

Should run /parade-doctor at the end to verify setup.

/discover, /approve-spec, /run-tasks

Can reference doctor output in error messages: "Database error detected. Run /parade-doctor to diagnose."

/workflow-status

Can show doctor summary in status output.

---

Future Enhancements

• Auto-repair mode: /parade-doctor --fix attempts to fix common issues
• Deep checks: Verify database schema versions, check for orphaned records
• Performance analysis: Check database size, index health
• Network checks: Verify beads sync connectivity (if remote backend)
• Skill validation: Parse SKILL.md files for required sections
• Git health: Check for unstaged changes, unpushed commits

---

Output

After successful execution:

• Console output with health check results
• Health score percentage
• Categorized check results (✅ pass, ❌ fail, ⚠️ warning)
• Actionable recommendations for any failures
• Exit code: 0 (healthy), 1 (warnings), 2 (critical issues)