fix

name	fix
description	Bug/issue fix pipeline: investigate → plan → review plan → implement (subagent-per-task with two-stage review) → review → verify build. Offers to create investigator agent when project reaches 50+ files.
disable-model-invocation	true

Fix Pipeline

You are the fix orchestrator. Drive this pipeline sequentially with human gates at each stage. You coordinate — subagents implement.

CRITICAL: This skill is gated by a UserPromptSubmit hook (.claude/hooks/plan-mode-gate.sh) that blocks invocation when Claude Code's plan mode is active — exit plan mode (Shift+Tab) and re-invoke. Pipeline gates are inline conversation prompts; never use EnterPlanMode/ExitPlanMode mid-pipeline. See ADR-009.

Context

• Changed files: !git diff --name-only HEAD 2>/dev/null || echo "clean"
• Current branch: !git branch --show-current 2>/dev/null || echo "no branch"

Issue to fix: $ARGUMENTS

Pre-flight migration check: If .ruckus/.migration-in-progress, .ruckus/known-pitfalls.md, or .ruckus/workflow-upgrades exists, abort with: "Legacy .ruckus/ state detected (v0.1.3 install or incomplete v0.1.4 migration). Run /roughly:upgrade to migrate or resume, then re-run." A .ruckus/ directory containing only user-extras (post-leave state from a completed upgrade) is fine — proceed.

---

STAGE 1: INTAKE

Parse $ARGUMENTS. Expected formats:

• File reference + issue ID: docs/issues/uat-issues.md ISSUE-001
• Direct description: "Login fails when session expires"
• File reference only: docs/bugs/crash-report.md

If it references a file, read it. If an issue ID is provided, extract that specific issue's details.

Display: issue summary, reproduction steps (if available), affected area.

Ask: "Is this the correct issue? (yes / adjust / abort)"

---

STAGE 2: INVESTIGATE

First, compact context to preserve headroom for investigation (investigation involves extensive search/read operations).

If investigator-v1-added is recorded in .roughly/workflow-upgrades, dispatch the investigator agent with the issue description.

If the investigator is not enabled, perform investigation inline:

1. Search for relevant code using the issue description
2. Trace the execution path
3. Identify the root cause or narrow candidates
4. Document findings

When investigation completes, display the report: root cause hypothesis, affected files, proposed fix approach.

Gate: "Investigation complete. Root cause: [summary]. Proceed to planning? (yes / investigate further / abort)"

---

STAGE 3: PLAN

Using the investigation report, write a fix plan. Same format as /roughly:build plans:

# Fix Plan: [issue ID or short description]

Plan-format-version: 1

## Root Cause
[One paragraph explaining why the bug exists]

## File Table
| File | Action | Task(s) |
|------|--------|---------|
| src/auth/session.ts | Modify | T1 |
| src/auth/session.test.ts | Create | T2 |

## Tasks

### T1: [short title] (~3 min)
**Files:** [file paths]
**Action:** [what to change]
**Details:** [specific implementation — enough for a fresh subagent]
**Verify:** [command to confirm the fix]
**UI:** no

### T2: [short title] (~3 min)
**Files:** [file paths]
**Depends on:** T1
**Action:** [add regression test]
**Details:** [specific test to write]
**Verify:** [test command]
**UI:** no

## Blast Radius
- Do NOT modify: [files outside scope]
- Watch for: [side effects]

Write the plan to: docs/plans/fix-<issue-id-or-name>-plan.md (e.g., fix-GH-42-plan.md)

Do NOT present the plan to the human yet — proceed directly to Stage 4.

---

STAGE 4: REVIEW PLAN

MANDATORY — this stage cannot be skipped. Do NOT present the plan to the human before this stage completes.

Pre-check: Before dispatching, verify the plan file from Stage 3:

1. Confirm the file exists at the expected path
2. Confirm it contains a ## Tasks section with at least one task (T1)
3. If either check fails: warn the human and loop back to Stage 3

Dispatch /roughly:review-plan as a blocking subagent call. Use model sonnet. Pass the plan file path from Stage 3 as the input.

If NEEDS REVISION: apply the suggested edits to the plan file, then re-dispatch the review-plan subagent against the updated plan. Repeat until PASS or until 2 total NEEDS REVISION verdicts — at that point, present findings to the human and let them decide.

After review completes: NOW present the plan and review results to the human. Display the plan summary, task count, root cause, and the review verdict (PASS or outstanding concerns).

Gate (only after PASS or explicit override): "Fix plan drafted with [N] tasks and verified against the codebase. [Review summary]. Ready to implement? (yes / revise plan / abort)"

Override protocol: If the human wants to proceed without PASS, they must explicitly say "override." Ambiguous responses ("skip it," "good enough," "it's fine") are NOT overrides — ask for clarification. When override is confirmed, display: "Proceeding without plan review PASS. The plan has not been verified against the codebase."

Compact context before implementation. Preserve: issue summary with root cause, plan file path, PASS verdict. The plan file on disk contains all implementation details — re-read it in Stage 5.

---

STAGE 5: IMPLEMENT (subagent-per-task)

Prerequisite: Stage 4 must have completed and been approved.

Re-read the plan file. If the path is no longer in context after Stage 4 compaction, check docs/plans/ for the most recent plan file matching the issue name or description.

5a. Create task tracking

Read the verified plan. Create a TodoWrite entry for each task. Note task dependencies — do not dispatch a task until its dependencies are marked complete.

5b. Execute tasks

For each task in order, dispatch a fresh implementation subagent. Use model sonnet.

Implementation subagent prompt (constructed per-task):

Fill in the {{VARIABLES}} below for this specific task. For UI tasks (UI: yes in the plan), include the "UI Task" section. For non-UI tasks (UI: no), omit the "UI Task" section entirely.

You are implementing a single task for {{PROJECT_NAME}}.

## Task

{{TASK_TITLE}}

**Files:** {{TASK_FILES}}
**Action:** {{TASK_ACTION}}
**Details:** {{TASK_DETAILS}}
**Verify:** {{TASK_VERIFY_COMMAND}}

## Context

Read CLAUDE.md and .roughly/known-pitfalls.md before implementing.

## UI Task (include ONLY when plan task has UI: yes — omit entirely for UI: no)

Invoke `frontend-design` skill if available. If unavailable, apply design system conventions from CLAUDE.md directly.

## Rules

- Implement ONLY this task — do NOT modify files outside the task's file list
- Run verification after changes: {{TASK_VERIFY_COMMAND}} — fix failures before returning
- If unclear or blocked, return a question instead of guessing

## Return

Files changed, verification result (pass/fail), any deviations or blocking questions.

5c. Two-stage review after each task

After each subagent returns:

Stage 1 — Spec compliance (orchestrator performs inline): Run the spec compliance checklist:

• Did the subagent modify only the files listed in the task?
• Did the verification command pass?
• Does the implementation match the task description?
• If the subagent returned questions: answer them, re-dispatch (max 2; then escalate to human).

Stage 2 — Quick quality check (orchestrator performs inline):

• Run the project's type check / lint command
• If it fails on files this task owns: attempt auto-fix (max 2 attempts); if still failing, escalate to human.
• If it fails on files outside this task's scope or on environmental issues (missing dependency, config error): escalate to human immediately.

If both stages pass: mark task complete, proceed to next task. If spec compliance fails: re-dispatch with clarified instructions OR escalate to human. If quality check auto-fix fails after 2 attempts: escalate to human.

5d. Completion

Gate: "Fix implemented. [N] tasks executed, all passing. Summary: [task list with status]. Proceed to review? (yes / adjust / abort)"

Compact context before review. Preserve: issue summary, task ID list, list of all files changed, task completion count, any verification warnings or deviations.

---

STAGE 6: REVIEW

MANDATORY — this stage cannot be skipped.

Invoke /roughly:review with a description of the fix. Fix critical findings and re-run (max 2 review-fix cycles; if still failing, present findings to human).

Gate: "Review complete. Proceed to verification? (yes / list warnings to address [then re-review once] / abort)"

Compact context before verification. Preserve: issue summary, files changed, review verdict, any deferred warnings.

---

STAGE 7: VERIFY

MANDATORY — this stage cannot be skipped.

Invoke /roughly:verify-all. Fix failures and re-run until clean.

Gate: "Verification passed. Ready to commit? (yes / additional checks / abort)"

Compact context before wrap-up. Preserve: issue summary with root cause, files changed, task completion count, verification verdict.

---

STAGE 8: WRAP-UP

1. git add changed files
2. Draft commit message:

   fix: [short description]
   
   Root cause: [one line]
   Issue: [issue ID if provided]
   Changes: [file list with one-line descriptions]
   Tested: [verification summary]
   

3. Show commit for approval. Commit but do NOT push.
4. Run maturity checks (see below).
5. Ask: "Did this fix reveal any new pitfalls or conventions for .roughly/known-pitfalls.md?" If yes, dispatch doc-writer agent.

---

MATURITY CHECKS (run at wrap-up)

Read .roughly/workflow-upgrades (create if missing).

Check IDs are versioned (e.g., investigator-v1). When the plugin updates a check, the version bumps and previously-declined checks are re-offered with an explanation of what changed. Format per entry: [check-id]-[added|declined] YYYY-MM-DD.

Three responses per upgrade:

• yes — apply, record [id]-added YYYY-MM-DD
• not yet — don't record (ask again next run)
• never — record [id]-declined (never ask again for this version)

Check: CLAUDE.md quality (every run, not gated by upgrades file): Read CLAUDE.md. If missing build command, type check command, or stack summary, warn:

"CLAUDE.md is missing [fields]. This reduces the quality of every Roughly skill. Run /roughly:setup to fix, or provide the missing info now." Continue with whatever the human provides — not a hard block, but a visible gap.

Check: investigator-v1: If no investigator-v1-added in .roughly/workflow-upgrades AND source file count > 50 AND not declined:

"This project has [N] source files but the investigator agent isn't enabled. It improves bug diagnosis for /roughly:fix. Enable it? (yes / not yet / never)" If yes: record investigator-v1-added YYYY-MM-DD in .roughly/workflow-upgrades. The agent definition ships with the plugin — no file copy needed.

Check: stop-hook-v1: If .claude/settings.json's .hooks.Stop is null, absent, or an empty array (i.e., no Stop hook is configured) AND verify-all has 2+ meaningful checks AND CLAUDE.md type-check is a real, runnable command (exclude both deliberate opt-outs none, none yet AND any placeholder values that may have slipped past Step 3 like skip, n/a, TBD, TODO, blank — defensive against post-setup CLAUDE.md edits) AND not declined:

"Verification is robust enough to enforce. Add a Stop hook? It runs type-check after every Claude turn — silent on success, surfaces drift. (yes / not yet / never)"

If yes: build/fix Stage 8 is the lighter, "you missed it during setup" install path — it does NOT replicate setup Branch 4's full transactional flow. Any failure aborts with a directional warning pointing to /roughly:setup for the canonical install. Sequence: (a) check jq is available; if not, warn + abort (no record — re-offer next run). (b) If .claude/settings.json exists, validate it parses cleanly (jq empty .claude/settings.json — note the explicit file argument; bare jq empty would read from stdin and not validate the file); if malformed, warn + abort. (c) If .claude/hooks/verify-all.sh already exists, warn the human that a hook file is already present and direct them to /roughly:setup for the keep/replace/merge/decline conflict prompt; abort with no record. (d) Validate that the substituted {{TYPE_CHECK_COMMAND}} from CLAUDE.md is a non-empty real command (an empty substitution would produce a bash syntax error in the installed hook); if empty, warn + abort. (e) mkdir -p .claude/hooks/; on failure, warn + abort. (f) Read template, substitute {{PROJECT_NAME}} and {{TYPE_CHECK_COMMAND}}, write to .claude/hooks/verify-all.sh, chmod +x. If write or chmod fails, rm the partial file (best-effort; if rm also fails, warn naming the orphan path) and abort. (g) If .claude/settings.json does not exist, create it with printf '%s' '{"hooks":{}}' > .claude/settings.json (the > redirect is required — bare printf writes to stdout); on failure, rm the just-written hook (best-effort; warn on rm failure) and abort. (h) Add the Stop entry via jq. If jq fails, rm the just-written hook (best-effort; if rm also fails, warn naming the orphan path so the user can remove it manually) and abort with no record. (i) On full success: record stop-hook-v1-added YYYY-MM-DD.

(If .hooks.Stop is a non-empty array when this gate fires — i.e., a Stop hook is already configured — skip silently. The gate above already excludes this case; it treats null/absent/empty array as "no Stop hook." The conflict prompt for an existing Stop hook lives in setup's Step 5d Branch 4 for the initial-install path, where it is reachable.)

If never: record stop-hook-v1-declined.

---

ABORT HANDLING

When the human selects "abort" at any gate, respond based on how far the pipeline progressed:

Stages 1-2 (no files written): Acknowledge abort. No cleanup needed.

Stages 3-4 (plan written, no implementation): Ask: "Delete the plan file at [path]? (yes / keep it)"

• If yes: delete the plan file
• Clear any TodoWrite entries created for this pipeline run

Stages 5-7 (implementation started): Offer rollback:

"Implementation is in progress. Options:

1. git stash -u — stash all uncommitted changes including new files (recoverable via git stash pop)
2. git reset --hard HEAD && git clean -fd — discard all uncommitted changes (staged and unstaged) and remove new files (irreversible — cannot be undone)
3. Keep changes as-is — leave working tree dirty for manual review"

If the human selects option 2, require explicit re-confirmation: "This will permanently delete all uncommitted changes. Type 'discard' to confirm."

Wait for human choice. Execute their selection. Then:

• Clear all TodoWrite entries for this pipeline run
• Delete the plan file only if the human also confirms

Always on abort: End with a clear message: "Pipeline aborted at Stage [N]. [cleanup summary]."