name: bug-health-inline description: Inline orchestration workflow for automated bug detection and fixing with Beads integration. Provides step-by-step phases for bug-hunter detection, priority-based fixing with bug-fixer, and verification cycles. version: 3.0.0

Bug Health Check (Inline Orchestration)

You ARE the orchestrator. Execute this workflow directly without spawning a separate orchestrator agent.

Workflow Overview

Beads Init → Detection → Create Issues → Fix by Priority → Close Issues → Verify → Beads Complete

Max iterations: 3 Priorities: critical → high → medium → low Beads integration: Automatic issue tracking

Phase 1: Pre-flight & Beads Init

Setup directories:

mkdir -p .tmp/current/{plans,changes,backups}

Validate environment:
- Check package.json exists
- Check type-check and build scripts exist
Create Beads wisp:
```
bd mol wisp healthcheck
```
IMPORTANT: Save the wisp ID (e.g., mc2-xxx) for later use.

Initialize TodoWrite:

[
  { "content": "Bug detection", "status": "in_progress", "activeForm": "Detecting bugs" },
  { "content": "Create Beads issues", "status": "pending", "activeForm": "Creating issues" },
  { "content": "Fix critical bugs", "status": "pending", "activeForm": "Fixing critical bugs" },
  { "content": "Fix high priority bugs", "status": "pending", "activeForm": "Fixing high bugs" },
  {
    "content": "Fix medium priority bugs",
    "status": "pending",
    "activeForm": "Fixing medium bugs"
  },
  { "content": "Fix low priority bugs", "status": "pending", "activeForm": "Fixing low bugs" },
  { "content": "Verification scan", "status": "pending", "activeForm": "Verifying fixes" },
  { "content": "Complete Beads wisp", "status": "pending", "activeForm": "Completing wisp" }
]

Phase 2: Detection

Invoke bug-hunter via Task tool:

subagent_type: "bug-hunter"
description: "Detect all bugs"
prompt: |
  Scan the entire codebase for bugs:
  - Run type-check and build
  - Check for security vulnerabilities
  - Find dead code and debug statements
  - Categorize by priority (critical/high/medium/low)

  Generate: bug-hunting-report.md

  Return summary with bug counts per priority.

After bug-hunter returns:

Read bug-hunting-report.md
Parse bug counts by priority
If zero bugs → skip to Phase 7 (Final Summary)
Update TodoWrite: mark detection complete

Phase 3: Create Beads Issues

For each bug found, create a Beads issue:

# Critical bugs (P1)
bd create "BUG: {bug_title}" -t bug -p 1 -d "{description}" \
  --deps discovered-from:{wisp_id}

# High bugs (P2)
bd create "BUG: {bug_title}" -t bug -p 2 -d "{description}" \
  --deps discovered-from:{wisp_id}

# Medium bugs (P3)
bd create "BUG: {bug_title}" -t bug -p 3 -d "{description}" \
  --deps discovered-from:{wisp_id}

# Low bugs (P4)
bd create "BUG: {bug_title}" -t bug -p 4 -d "{description}" \
  --deps discovered-from:{wisp_id}

Track issue IDs in a mapping:

bug_1 → mc2-aaa
bug_2 → mc2-bbb
...

Update TodoWrite: mark "Create Beads issues" complete.

Phase 4: Quality Gate (Pre-fix)

Run inline validation:

pnpm type-check
pnpm build

If both pass → proceed to fixing
If fail → report to user, exit

Phase 5: Fixing Loop

For each priority (critical → high → medium → low):

Check if bugs exist for this priority
- If zero → skip to next priority
Update TodoWrite: mark current priority in_progress

Claim issues in Beads:

bd update {issue_id} --status in_progress

Invoke bug-fixer via Task tool:

subagent_type: "bug-fixer"
description: "Fix {priority} bugs"
prompt: |
  Read bug-hunting-report.md and fix all {priority} priority bugs.

  For each bug:
  1. Backup file before editing
  2. Implement fix
  3. Log change to .tmp/current/changes/bug-changes.json

  Generate/update: bug-fixes-implemented.md

  Return: count of fixed bugs, count of failed fixes, list of fixed bug IDs.

Quality Gate (inline):
```
pnpm type-check
pnpm build
```
- If FAIL → report error, suggest rollback, exit
- If PASS → continue

Close fixed issues in Beads:

bd close {issue_id_1} {issue_id_2} ... --reason "Fixed in health check"

Update TodoWrite: mark priority complete
Repeat for next priority

Phase 6: Verification

After all priorities fixed:

Update TodoWrite: mark verification in_progress

Invoke bug-hunter (verification mode):

subagent_type: "bug-hunter"
description: "Verification scan"
prompt: |
  Re-scan codebase after fixes.
  Compare with previous bug-hunting-report.md.

  Report:
  - Bugs fixed (count)
  - Bugs remaining (count)
  - New bugs introduced (count)

Decision:
- If bugs_remaining == 0 → Phase 7
- If iteration < 3 AND bugs_remaining > 0 → Go to Phase 2
- If iteration >= 3 → Phase 7 with remaining bugs

Phase 7: Final Summary & Beads Complete

Complete Beads wisp:

# If all bugs fixed
bd mol squash {wisp_id}

# If no bugs found (nothing to do)
bd mol burn {wisp_id}

Create issues for remaining bugs (if any):

bd create "REMAINING: {bug_title}" -t bug -p {priority} \
  -d "Not fixed in health check. See bug-hunting-report.md"

Generate summary for user:

## Bug Health Check Complete

**Wisp ID**: {wisp_id}
**Iterations**: {count}/3
**Status**: {SUCCESS/PARTIAL}

### Results

- Found: {total} bugs
- Fixed: {fixed} ({percentage}%)
- Remaining: {remaining}

### By Priority

- Critical: {fixed}/{total}
- High: {fixed}/{total}
- Medium: {fixed}/{total}
- Low: {fixed}/{total}

### Beads Issues

- Created: {count}
- Closed: {count}
- Remaining: {count} (issues created for follow-up)

### Validation

- Type Check: {status}
- Build: {status}

### Artifacts

- Detection: `bug-hunting-report.md`
- Fixes: `bug-fixes-implemented.md`

Update TodoWrite: mark wisp complete

SESSION CLOSE PROTOCOL:

git status
git add .
bd sync
git commit -m "fix: health check - {fixed} bugs fixed ({wisp_id})"
bd sync
git push

Error Handling

If quality gate fails:

Rollback available: .tmp/current/changes/bug-changes.json

To rollback:
1. Read changes log
2. Restore files from .tmp/current/backups/
3. Re-run workflow

If worker fails:

Report error to user
Keep Beads wisp open for manual completion
Suggest manual intervention
Exit workflow

If Beads command fails:

Log error but continue workflow
Beads tracking is enhancement, not blocker

Quick Reference

Phase	Beads Action
1. Pre-flight	`bd mol wisp healthcheck`
3. After detection	`bd create` for each bug
5. Before fix	`bd update --status in_progress`
5. After fix	`bd close --reason "Fixed"`
7. Complete	`bd mol squash/burn`
7. Remaining	`bd create` for unfixed bugs

Worker Prompts

See references/worker-prompts.md for detailed prompts.

bug-health-inline

SKILL.md