From soloflow
Investigates provided bug report, identifies root cause, resolves via executor agent, verifies fix with shadow-verifier, and adds regression test. Optional --no-confirm.
npx claudepluginhub kesteva/soloflow --plugin soloflow-dev<bug report — symptoms, expected vs actual, optional reproduction steps> [--no-confirm]# /soloflow:bugfix You are running the SoloFlow bugfix workflow. The user has reported a bug. Your job is to: 1. **Identify** the bug — spawn the bug-investigator to do read-only root-cause analysis. 2. **Confirm** the hypothesis with the user (unless `--no-confirm` is in `$ARGUMENTS`). 3. **Resolve** the bug — spawn the executor with a precise plan derived from the investigation. 4. **Verify** the fix — spawn shadow-verifier; on `NEEDS_CHANGES`, retry the executor. 5. **Lock it in** — spawn test-writer to add a regression test. This command is a sibling of `/soloflow:quick`. Both run a ...
/bugfixOrchestrates bugfix workflow: analyzes error, implements fix via sub-agents, iteratively validates quality up to 3 rounds until >=90%, outputs production-ready fix and report.
/bugfixExecutes end-to-end bug fix workflow: root cause analysis via 5 Whys, user review of findings, then TDD regression test + fix delivery.
/bugfixFixes frontend bugs via multi-layer detection (React/Vue/Angular), iterative sub-agent repairs with quality verification loops until 90% score or 3 max iterations.
/bugfixDocuments bug fixes via interactive interview on problem reproduction, root cause analysis, fix approach, and regression testing strategy.
/bugfixFixes bugs using severity-based workflows: quick for simple issues, full investigation for complex bugs, hotfix for production emergencies. Supports interactive mode.
/bugfixTDD-driven bugfix workflow: tester writes failing test (RED) → developer fixes (GREEN) → developer refactors (REFACTOR) → reviewer validates. Accepts issue number, description, or both. Auto-creates PR unless --no-pr flag is passed.
Share bugs, ideas, or general feedback.
You are running the SoloFlow bugfix workflow. The user has reported a bug. Your job is to:
--no-confirm is in $ARGUMENTS).NEEDS_CHANGES, retry the executor.This command is a sibling of /soloflow:quick. Both run a single task inline (no run branch, no worktree, no parallelism, no per-task code review). The difference: /quick assumes the user already knows the fix; /bugfix performs a dedicated investigation step first and gates on user confirmation before any code changes.
The bug report is: $ARGUMENTS
Parse $ARGUMENTS for the optional --no-confirm flag. If present, strip it from the bug report text before passing the rest to the investigator, and skip the confirmation gate in Step 4.
Run once at the start, cache the result:
node "${CLAUDE_PLUGIN_ROOT}/scripts/config/resolve.js" --all
Keys consumed:
models.bug_investigator (fallback: opus) — the investigator runs Opus by default for judgment.models.executor / models.test_writer (fallback: sonnet)models.verifier (fallback: opus)limits.executor_retry_max (fallback: 3) — cap on NEEDS_CHANGES retries in Step 8.limits.context_limit_respawn_max (fallback: 3) — cap on CONTEXT_LIMIT respawns for any agent.Reuse the cached values across all agent spawns and respawns. Also cap investigator re-spawns (after INVESTIGATION_INCONCLUSIVE + new user input in Step 3) at 2 — independent of the context-limit budget.
If .soloflow/ does not exist, report: "SoloFlow not initialized. Run /soloflow:init first." and stop.
Use the Agent tool with subagent_type: "bug-investigator" and the cached models.bug_investigator. Prompt body:
Investigate this bug report. Produce a structured root-cause analysis. Do NOT write code.
Bug report:
{user's $ARGUMENTS, with --no-confirm stripped}
Wait for the investigator's report and read its verdict.
ROOT_CAUSE_FOUND → proceed to Step 4 (confirmation gate).
INVESTIGATION_INCONCLUSIVE → present the report's Reproduction Blockers and Alternatives Considered to the user. Use AskUserQuestion with options:
If the cap is hit, write a one-line entry to .soloflow/human-review-queue.md (use the canonical schema from commands/quick.md Step 7 HUMAN_NEEDED branch, with type: investigation_inconclusive, task: null, and bucket: decisions — investigation outcomes that cannot converge are always judgment calls for the user) and stop. No TASK-NNN is allocated when investigation never converges.
NOT_A_BUG → present the investigator's reasoning to the user and stop. Do not allocate a TASK-NNN. Suggest the user file /soloflow:idea-extractor if they actually want a behavior change.
CONTEXT_LIMIT → read the ### Handoff section. If respawns < limits.context_limit_respawn_max, spawn a fresh investigator with the original report + "Continue from previous investigator's handoff: {handoff section}". Otherwise treat as INVESTIGATION_INCONCLUSIVE (run the cap-hit branch).
Skip this step entirely if --no-confirm was in $ARGUMENTS. Otherwise, use AskUserQuestion to surface the investigator's hypothesis:
Frame the question around the investigator's Root Cause, Affected Files, Proposed Fix, and Confidence. Options:
Refine rounds against it.If the investigator's Confidence is low, treat the gate as required even if --no-confirm was set — the user did not opt into autonomous mode for low-confidence diagnoses. Print a one-line note explaining the override.
Compute the next task ID using the shared recipe (same as commands/quick.md Step 3):
Glob every TASK file location:
.soloflow/active/plans/**/TASK-*-plan.md.soloflow/active/stuck/**/TASK-*-stuck.md.soloflow/archive/done/**/TASK-*-done.mdExtract numeric suffixes and take max + 1 (zero-padded to 3 digits).
Write .soloflow/active/plans/TASK-{NNN}-plan.md with noclobber/wx semantics; if it exists (parallel-worker race), recompute the next ID and retry. Format:
---
id: TASK-{NNN}
idea: inline
status: approved
created: {ISO timestamp}
files_owned:
- {paths from investigator's affected_files where role is fault, symptom, or test_target}
files_readonly:
- {paths from investigator's affected_files where role is context}
acceptance_criteria:
- criterion: "Reproduction steps no longer trigger the bug"
verification: "{how — derive from investigator's Reproduction section}"
- criterion: "Regression test exists and passes"
verification: "Test at {path from test_target affected_file} runs and passes"
- {any additional behavioral criteria the investigator surfaced}
depends_on: []
estimated_complexity: low|medium|high
---
# Bugfix: {one-line summary from investigator's Bug Summary}
## Bug Summary
{Copy investigator's Bug Summary verbatim}
## Root Cause
{Copy investigator's Root Cause verbatim}
## Reproduction
{Copy investigator's Reproduction verbatim}
## Implementation Steps
{Derive from investigator's Proposed Fix. Be concrete: each step references a specific file and function. The investigator gave you the prescription; turn it into ordered, imperative steps.}
## Acceptance Criteria
{Restate each criterion from the frontmatter with clear pass/fail definitions.}
If the investigator's affected_files list is empty (which should not happen for ROOT_CAUSE_FOUND but guard anyway), stop with an error — do not invent files.
Add the task entry to sprint.json and create the per-sprint findings file. Use the same recipe as commands/quick.md Step 3:
node "${CLAUDE_PLUGIN_ROOT}/scripts/state/update-task-status.js" TASK-{NNN} in_progress --create --plan .soloflow/active/plans/TASK-{NNN}-plan.md
--create scaffolds sprint.json with a SPRINT-bugfix-<timestamp> id if it doesn't exist yet. (The bugfix prefix mirrors /quick's SPRINT-quick-<timestamp> so downstream tooling can tell at a glance how a sprint was created.)
After --create completes, read .soloflow/sprint.json (or .soloflow/active/sprint.json — check both) to get sprint.id. Call this value {sprint_id} for the rest of the command. Ensure .soloflow/active/findings/ exists. If .soloflow/active/findings/{sprint_id}-findings.md does not exist, create it with wx/noclobber semantics:
---
sprint: {sprint_id}
pending_count: 0
last_updated: null
---
# Findings Queue
Use the Agent tool with subagent_type: "executor" and the cached models.executor. Prompt:
Implement this task plan. Follow every step. Report your status when done.
{full content of the plan file}
Wait for the executor's status report.
node "${CLAUDE_PLUGIN_ROOT}/scripts/state/settle-task.js" TASK-{NNN} blocked --touched .soloflow/active/plans/TASK-{NNN}-plan.md --touched .soloflow/active/findings/{sprint_id}-findings.md. Report the blocker. Stop..soloflow/active/stuck/TASK-{NNN}-stuck.md with the executor's error details. Run settle-task.js TASK-{NNN} stuck --stuck-report ... --touched .... Report. Stop.### Handoff. If respawns < limits.context_limit_respawn_max, spawn a fresh executor with the plan + "Continue from previous executor's handoff: {handoff}". Otherwise escalate as STUCK.Use the Agent tool with subagent_type: "shadow-verifier" and the cached models.verifier. Prompt:
Verify this completed task. The plan and executor report are below. Run all checks independently.
PLAN:
{full plan file content}
EXECUTOR REPORT:
{executor's status report verbatim}
The plan's first acceptance criterion ("Reproduction steps no longer trigger the bug") will route the verifier through Level 1 (run tests) and/or Level 2 (visual reproduction) per its standard 5-level hierarchy — no bugfix-specific verification logic is needed.
Wait for the verdict.
limits.executor_retry_max):
Changes Required appended to the prompt: "Previous attempt had issues. The verifier found: {Changes Required block}. Fix these specific issues." Increment the loop counter, then re-verify (back to Step 9).settle-task.js TASK-{NNN} stuck .... Report that the fix needs human intervention. Stop..soloflow/human-review-queue.md from the verifier; the final summary should mention them..soloflow/human-review-queue.md using the canonical schema from commands/quick.md Step 7 HUMAN_NEEDED branch (with task: TASK-{NNN}, type: HUMAN_NEEDED, plan_ref, verdict_notes, action, severity). Run settle-task.js TASK-{NNN} human_needed .... Report. Stop.limits.context_limit_respawn_max). On exhaustion, log to human-review-queue and stop.Use the Agent tool with subagent_type: "test-writer" and the cached models.test_writer. Prompt:
Add a regression test for this bug so it cannot recur. The plan, executor changes, and verifier report are below. No code-review report (bugfix path skips per-task code review).
PLAN:
{full plan file content}
EXECUTOR CHANGES:
{from executor report — files modified and commits}
VERIFIER REPORT:
{verifier report verbatim}
If the executor or investigator already wrote a regression test (e.g., the reproduction in the plan was a unit test), test-writer will recognize that and confirm rather than duplicate.
Handle test-writer outcomes per the standard pattern (TESTS_WRITTEN → run suite, one retry on failure, then log a finding and proceed; NO_TESTS_NEEDED / NO_TEST_INFRA → proceed; CONTEXT_LIMIT → respawn).
Write .soloflow/archive/done/TASK-{NNN}-done.md with frontmatter (using the schema referenced in commands/quick.md Step 7 APPROVED branch):
---
id: TASK-{NNN}
status: done
summary: "{one-line summary of the fix}"
executor_loops: {your loop counter — 1 if approved first try}
code_review_rounds: 0 # bugfix path skips per-task code review, same as /quick
visual_mobile: {verbatim from verifier's Visual Verification report}
visual_web: {verbatim from verifier's Visual Verification report}
investigation_confidence: {verbatim from investigator's Confidence}
---
The investigation_confidence field is bugfix-specific — it lets the compounder later notice patterns like "low-confidence investigations correlate with NEEDS_CHANGES retries." Other done-report consumers ignore unrecognized fields, so adding it here does not break anything.
Then run:
node "${CLAUDE_PLUGIN_ROOT}/scripts/state/settle-task.js" TASK-{NNN} done --done-report .soloflow/archive/done/TASK-{NNN}-done.md --touched .soloflow/active/plans/TASK-{NNN}-plan.md --touched .soloflow/active/findings/{sprint_id}-findings.md
This removes the task from sprint.json and commits chore(TASK-{NNN}): done.
Report to the user:
## SoloFlow Bugfix — Summary
- **Task:** TASK-{NNN}
- **Verdict:** {APPROVED | STUCK | HUMAN_NEEDED}
- **Root cause:** {one-line from investigator's Root Cause}
- **Investigation confidence:** {high | medium | low}
- **Executor loops:** {count}
- **Files changed:** {list from executor report}
- **Regression test:** {path written by test-writer, or "already existed: {path}"}
- **Commits:** {list}
If any deferred or human-review items were queued during the run, list them under a "Human review needed" section pointing at .soloflow/human-review-queue.md.
/soloflow:quick instead. The investigator is the whole point of /bugfix./quick. If a bugfix surfaces broader concerns, the verifier flags them as findings; the compounder picks them up. For deeper review, the user can run /soloflow:sprint against backlog tasks where code review is on by default.--no-confirm is for autonomous use (e.g., scripted bug triage on a CI worker). Always print the investigator's hypothesis before proceeding so the user can read it after the fact, and override --no-confirm when confidence is low (see Step 4).This command runs in the main session. The context-monitor hook injects warnings when context usage is high.
When you receive a SOLOFLOW CONTEXT WARNING: finish the current step, then write a checkpoint.
When you receive a SOLOFLOW CONTEXT CRITICAL: finish the current subagent interaction, write a checkpoint, then use AskUserQuestion with options: Compact and continue / Save and exit.