Fix Pipeline
Relevant source files
The following files were used as context for generating this wiki page:
The Fix Pipeline is a specialized development workflow within the Roughly plugin designed to diagnose and repair bugs or issues. It utilizes an 8-stage gated process that separates orchestration from implementation. The orchestrator manages the high-level flow and human confirmation gates, while fresh subagents are dispatched to handle specific investigation and implementation tasks.
This pipeline is distinguished from the Build Pipeline by its focus on investigation rather than discovery and its use of corrective fix: commit messages. It is designed to be "loud" and "gated," ensuring no silent transitions occur between diagnostic findings, planning, and code changes.
Sources: README.md:162-167, skills/fix/SKILL.md:1-12
Pipeline Architecture and Stages
The Fix Pipeline follows a linear sequence of eight stages, each separated by a human confirmation gate. If CI_MODE is enabled via the --ci flag, these gates auto-proceed or exit with error codes upon failure.
The diagram shows the sequential flow of the 8-stage Fix Pipeline and the mandatory human gates between phases.
Sources: skills/fix/SKILL.md:162-167, README.md:172-177
Stage 1: Intake
The pipeline begins by parsing arguments which can be file references, issue IDs, or direct descriptions. The orchestrator identifies the affected area and reproduction steps before seeking human confirmation to proceed.
Sources: skills/fix/SKILL.md:27-46
Stage 2: Investigate
Unlike the Build pipeline's discovery phase, this stage focuses on root cause analysis.
- Investigator Agent: If the project is "Established" (50+ files), a specialized
investigatoragent is dispatched. - Inline Investigation: In smaller projects, the orchestrator performs searches and execution path tracing manually.
The result is an investigation report containing a root cause hypothesis and a proposed fix approach.
Sources: skills/fix/SKILL.md:48-60, README.md:267-270
Stage 3 & 4: Planning and Review
The orchestrator drafts a Fix Plan containing a root cause description, a file table, and discrete tasks (T1, T2, etc.). Each task specifies files, actions, details, verification commands, and a UI: yes/no flag.
- Mandatory Review: Stage 4 dispatches a
review-plansubagent to verify the plan against the codebase. - Revision Loop: If the review returns
NEEDS REVISION, the orchestrator attempts to auto-edit the plan (up to 2 iterations) before escalating to the human.
Sources: skills/fix/SKILL.md:62-114, skills/review-plan/SKILL.md:13-17
Implementation and Quality Control
Stage 5: Implementation (Subagent-per-Task)
Implementation is performed by fresh subagents for each task in the plan. This "Subagent-per-task" model prevents context overflow by giving each implementation step a clean environment.
The sequence diagram illustrates the loop where the orchestrator dispatches fresh subagents for individual tasks and performs immediate quality checks.
Sources: skills/fix/SKILL.md:121-180, README.md:118-122
Two-Stage Task Review
After each task, the orchestrator performs an inline check:
- Spec Compliance: Verifies the agent modified only the listed files and followed instructions.
- Quality Check: Runs project type-checks, lints, and tests. The orchestrator may attempt up to 4 auto-fixes for type/lint errors and 2 for test failures.
Sources: skills/fix/SKILL.md:182-205, CLAUDE.md:73-77
Stage 6 & 7: Global Review and Verification
- Global Review: Stage 6 invokes the
/roughly:reviewskill, which runs three parallel agents (code-reviewer,static-analysis,silent-failure-hunter) to find bugs or security issues across the entire fix. - Verification: Stage 7 runs
/roughly:verify-allto ensure the entire project builds and passes all checks.
Sources: skills/fix/SKILL.md:212-243, README.md:154-159
Wrap-up and Documentation
The final stage handles the transition of the fix from an active artifact to a historical record.
| Action | Description |
|---|---|
| Git Commit | Creates a commit with the fix: prefix, root cause, and issue ID. |
| Historical Marking | Prepends a status block to the plan file marking it as "Historical — implemented and merged." |
| Pitfall Discovery | Asks if new pitfalls were found; if so, dispatches the doc-writer agent. |
| Maturity Checks | Offers project upgrades like adding a Stop hook or enabling the Investigator agent. |
Sources: skills/shared/stage-8-wrap-up.md:6-25, skills/fix/SKILL.md:248-285
Commit Message Format
When invoked from the fix pipeline, the commit message follows a specific structure:
fix: [short description]
Root cause: [one line]
Issue: [issue ID if provided]
Changes: [file list with descriptions]
Tested: [verification summary]
Sources: skills/shared/stage-8-wrap-up.md:16-22
Operational Constraints
Plan Mode Protection
The Fix Pipeline is gated by a plan-mode-gate.sh hook. It cannot be invoked while Claude Code is in "Plan Mode" to prevent nested execution conflicts. Users must exit plan mode before running /roughly:fix.
Sources: skills/fix/SKILL.md:7-11, CLAUDE.md:114-116
Abort Handling
If the pipeline is aborted at any gate, the system follows a standard procedure:
- Rollback: Offers to undo changes via
git checkoutorgit clean. - Cleanup: Removes the plan file if it wasn't consumed.
Sources: skills/fix/SKILL.md:290-291, CONTRIBUTING.md:200-205
The Fix Pipeline provides a structured, multi-agent approach to bug fixing that emphasizes diagnostic accuracy and automated quality enforcement through the use of isolated subagents and rigorous human-in-the-loop gates.