From doctor-triage
Diagnoses and fixes health issues in Gas Town (gt) and Beads (bd) workspaces using doctor CLI commands. Triages warnings into auto-fixable, manual fixes, or upstream bugs. For tooling misconfigurations.
npx claudepluginhub xexr/marketplace --plugin doctor-triageThis skill uses the workspace's default tool permissions.
Run diagnostic checks on a Gas Town or beads workspace, interpret each finding, fix what's fixable, and surface unfixable issues that may be upstream bugs worth filing as beads.
Audits Beislið workflow config in .beislid/workflow.md by probing capabilities against host session, reporting gaps in conversational prose, and caching results. Use /doctor, after editing config, or with --refresh.
Orchestrates bug-fixing workflow: clarify symptoms, reproduce with failing tests, diagnose root cause, implement targeted fixes, verify, review, and document. Use for thorough bug investigations.
Diagnoses and fixes broken devboy-tools setups including corrupt configs, missing tokens, keychain trouble, wrong paths, and plugin install failures. Use when devboy doctor fails or tools return unexpected errors.
Share bugs, ideas, or general feedback.
Run diagnostic checks on a Gas Town or beads workspace, interpret each finding, fix what's fixable, and surface unfixable issues that may be upstream bugs worth filing as beads.
gastown-rig-setup)systematic-debugging)Verify the required tools are available before proceeding:
gt --version 2>/dev/null
bd --version 2>/dev/null
gt is available → skip beads diagnostics, only offer "Gas Town (gt doctor)"bd is available → skip Gas Town diagnostics, only offer "Beads (bd doctor)"Use AskUserQuestion:
"Which workspace do you want to diagnose?"
Options:
- "Gas Town (gt doctor)" — Town-wide: clones, daemon, Dolt, patrols, sessions
- "Beads (bd doctor)" — Repo-level: database, schema, hooks, dependencies
- "Both" — Run gt doctor first, then bd doctor
gt doctor -v
Key flags if issues found:
gt doctor --fix — auto-fix fixable issuesgt doctor --rig <name> — check specific rig onlygt doctor --fix --restart-sessions — also restart stale patrol sessionsRun from the relevant repo root (or mayor/rig/ for Gas Town rigs):
bd doctor -v
Key flags if issues found:
bd doctor --fix — auto-fix with confirmationbd doctor --deep — full graph integrity validationbd doctor --server — Dolt server connectivity checksbd doctor --check=validate --fix — data-integrity repairsParse each warning/error into one of three categories:
| Category | Action |
|---|---|
| Auto-fixable | Run --fix and verify resolution |
| Manually fixable | Investigate root cause, apply targeted fix, verify |
| Unfixable / upstream bug | Explain to user, collect for Step 5 |
Do NOT blindly loop --fix. If --fix didn't resolve an issue on the first pass, investigate manually. Looping --fix can cycle without progress.
Do NOT restart the daemon unless the user asks or the diagnostic specifically recommends it.
Known false positives to skip:
bd doctor reports "No dolt database found" in server mode — this checks for local .beads/dolt/ which doesn't exist with a centralized Dolt server. Verify with bd list instead.For each auto-fixable or manually fixable issue:
After all fixes, run a final clean check:
# Gas Town
gt doctor -v
# Beads
bd doctor -v
This step is MANDATORY after every doctor run, even if all checks pass or all issues were fixed. Do not skip it.
After all fixes are applied and the final clean check is done, review the entire session:
--fix resolved — Were any of these symptoms of deeper bugs? (e.g., fix worked but required workarounds, fix needed multiple passes, fix hint was wrong)--fix automation?--fix failed to resolve — Why? Silent failure? Missing capability?Build a list of candidate upstream bugs. Include anything that is NOT a configuration problem — i.e., something that would affect any user of gt/bd, not just this workspace.
If NO candidates were identified, briefly state: "No upstream bugs identified — all issues were configuration-related." and skip to the end.
If candidates were identified, explain what was found and offer an escape hatch:
Use AskUserQuestion:
"I identified [N] potential upstream gt/bd issues during this doctor run — things that would affect any user, not just this workspace. Would you like to capture beads documenting these?"
Options:
- "Yes — show me what you found" — Review and selectively file beads
- "No — just fix my workspace" — Skip bug filing entirely
If the user declines, stop here. Do not proceed to 5c/5d.
If the user accepts, present the specific candidates:
Use AskUserQuestion with multiSelect:
"Which issues should we file?"
Options (multiSelect):
- "#1 [short title]" — [what happened, why it's a bug, not a config issue]
- "#2 [short title]" — [what happened, why it's a bug, not a config issue]
- ...
If no issues are selected, stop here.
The user may have different rigs set up for tracking bugs. Do NOT assume a specific rig.
Use AskUserQuestion:
"Which rig should these bugs be filed in?"
Options:
- List each rig from `gt rig list` output
- Include a description hint: for a rig named "gastown", say "Gas Town codebase (gt bugs)"
- For a rig named "beads", say "Beads codebase (bd bugs)"
If bugs span both gt and bd codebases, ask once and let the user choose — or offer "Split by codebase" to file gt bugs in one rig and bd bugs in another.
For each selected bug, create a bead using bd q (quick capture):
bd q -p P2 -l bug -l gastown -l "gt-doctor" "<title>"
# or for beads bugs:
# bd q -p P2 -l bug -l beads -l "bd-doctor" "<title>"
Then add a detailed description with bd update:
bd update <id> --description "<description>"
Description template:
## Bug
[What went wrong — observable behavior]
## Expected Behavior
[What should have happened]
## Actual Behavior
[What actually happened, including exact error output or silent failure]
## Reproduction
1. [Step-by-step to reproduce]
## Workaround
[If one was applied during this session]
## Environment
- gt version: [from `gt --version` or stale-binary check output]
- bd version: [from `bd --version` or beads-binary check output]
- Platform: [OS]
Labels:
bug — alwaysgastown or beads — based on which codebase the bug is ingt-doctor or bd-doctor — to group doctor-specific bugsPriority:
| Tool | Basic | Verbose | Fix | Deep |
|---|---|---|---|---|
gt doctor | gt doctor | gt doctor -v | gt doctor --fix | N/A |
bd doctor | bd doctor | bd doctor -v | bd doctor --fix | bd doctor --deep |
| Scenario | Command |
|---|---|
| After upstream sync | gt doctor -v then bd doctor -v |
| After rig addition | gt doctor --rig <name> then bd doctor -v (from rig) |
| Dolt connectivity | bd doctor --server |
| Data integrity | bd doctor --check=validate --fix |
| Stale sessions | gt doctor --fix --restart-sessions |
| Mistake | Fix |
|---|---|
Looping --fix when it doesn't resolve | Investigate manually after first --fix attempt |
Running bd doctor from wrong directory | Must be in repo root or mayor/rig/ for Gas Town rigs |
| Treating server-mode "No dolt database" as real | Use bd list to verify — it's a false positive |
| Restarting daemon for every issue | Only restart when diagnostic says to or user asks |
Using gt up --restart for stale settings | gt up --restart doesn't exist. Use gt doctor --fix --restart-sessions to delete stale Claude settings and recreate them properly |