Bug
bug is a pipeline-layer request type that diagnoses and fixes a defect through a lean version of the staged lifecycle. It runs under the orchestrator like any pipeline job, but its preset disables the exploratory and presentational stages — there is no brainstorm, no document, and no review by default — so the job goes straight from clarifying the defect to planning, executing, testing, and validating the fix.
The registry at _processes/_shared/request-types.md is the single source of truth for this type; its preset at _processes/_shared/presets/bug.md seeds the JOB.md the orchestrator's creation/bootstrap step writes.
The flow
A bug job runs the same orchestrator-driven pipeline as every pipeline type, but the preset enables only five of the eight stages. The orchestrator dispatches each enabled stage in canonical order — clarify → plan → execute → test → validate — verifies its artifact, parses its handoff, and writes the shared job state. The diagram below shows that lean spine.
(disabled) on a default bug job and do not appear in the flow above: brainstorm (bugs are usually scoped, not exploratory), document (the fix is usually internal), and review (the optional adversarial code-review pass stays off). The orchestrator skips any stage carrying the (disabled) marker.
What it is for
Reach for bug when you have a known defect to diagnose and fix — a regression, a crash, an incorrect result, a broken edge case. The work is typically scoped rather than open-ended, so the pipeline is deliberately lean: it skips the divergent-thinking and documentation work that a feature needs, and concentrates effort on understanding the defect, fixing it, and proving the fix with tests.
The lean shape is intentional. A bug fix usually has one correct approach once the cause is understood, so the brainstorm stage adds little; the change is usually internal, so the document stage is off; and the lighter scope means the optional review stage stays disabled unless you opt in. What stays on is the spine that catches the costly mistakes: clarify (so you do not plan a fix for code that already changed or lives elsewhere), plan, execute, test (to cover the fix), and validate (the adversarial backstop).
document by removing its (disabled) marker in JOB.md before promoting (or via the extend op-card later). The same applies to brainstorm and review — the preset only sets the lean defaults; you can widen any pipeline job.
The logic
In the registry, bug carries layer pipeline and shape pipeline. That pairing tells the orchestrator to run the staged lifecycle: at pickup it reads JOB.md → Type, looks up the layer in _processes/_shared/request-types.md, sees pipeline, and builds a stage run-plan from ## Stages instead of routing to an action prompt. Its prompt path is _processes/02_orchestrator/orchestrator.prompt.md — the same single lifecycle agent every pipeline type uses.
Stages the bug preset disables
The preset at _processes/_shared/presets/bug.md turns three stages off; the orchestrator skips every stage that carries the (disabled) marker in JOB.md → Stages.
- brainstorm
(disabled)— bugs are typically scoped, not exploratory, so the dual-writer divergence adds little. - document
(disabled)— the fix is usually internal; enable it manually only when the bug exposes a documentation gap. - review
(disabled)— the optional Codex adversarial review pass stays off for the lighter scope.
The gates that apply
The bug preset sets the approval gates so the pipeline runs unattended through diagnosis and the fix, then pauses before anything touches the remote.
after_creation: no,after_clarify: no,after_brainstorm: no,before_plan: no,before_execution: no— the orchestrator advances through creation, clarify, planning, and execution without stopping.before_commit: yesandbefore_pr: yes— the two Git gates are on, because reverting a bad fix is more expensive than a short pause to review the diff before it commits and before it opens a PR. Both fire at the post-validate git landing (orchestrator §I; D-63), after the final validate PASS.
clarify is enabled — it pressure-tests the defect report against the live codebase and catches the "this is already fixed in branch X" or "this lives in a different module than you thought" cases that would otherwise waste a plan + execute cycle.
The fields
A bug job uses the standard pipeline JOB.md shape (template: _processes/_shared/templates/JOB.template.md; contract: _processes/_shared/schemas/JOB_CONTRACT.md). The values below are the preset defaults the orchestrator's creation/bootstrap step seeds; you can override any of them in the intake or while reviewing in 1_creation/.
Header
| Field | Value |
|---|---|
Workflow version | 0.14 |
Type | bug |
Preset | _processes/_shared/presets/bug.md |
Created | YYYY-MM-DD |
Status | mirror of the queue folder (informational only) |
Base branch | main |
Target branch | bug/<slug> (a branch is created) or N/A |
## Git
| Line | Value |
|---|---|
| Create branch | yes |
| Validate against main | yes |
| Commit | yes — committed at the post-validate git landing, gated by before_commit (D-63) |
| Push | yes — the job branch is pushed to origin right after the commit (D-82), on any remote host |
| PR | yes — opened by the workflow at the same landing, gated by before_pr (merging stays yours) |
| PR target branch | (blank) ⇒ production — the branch the PR merges INTO (0.14, D-63); distinct from Base branch (cut FROM, default main) |
## Stages
All eight stages are listed in canonical order; the three the preset disables carry the (disabled) marker.
| Stage | State |
|---|---|
| clarify | enabled |
| brainstorm | (disabled) |
| plan | enabled |
| execute | enabled |
| test | enabled |
| document | (disabled) |
| review | (disabled) |
| validate | enabled |
## Approval gates
| Gate | Value |
|---|---|
| after_creation | no |
| after_clarify | no |
| after_brainstorm | no |
| before_plan | no |
| before_execution | no |
| before_commit | yes |
| before_pr | yes |
## Per-stage config (enabled stages only)
One sub-section per enabled stage. clarify is enabled but carries no config block — its mandate-rewrite carve-out is policy, not a toggle. The disabled stages (brainstorm, document, review) have no config block.
| Stage | Config (preset default) |
|---|---|
### Plan | Multi-phase: no (bug fixes are usually single-phase; override per job) |
### Execute | Delegate research to sub-agents: no (override per job) |
### Test | Unit: yes — tests cover the fix |
### Validate | Cross-check against mandate: yes; Agent: claude (override to codex per job to run validate's internal code review on Codex) |
How to run it
A bug job runs under the single lifecycle agent — the orchestrator. Copy its prompt path and send it to your agent:
_processes/02_orchestrator/orchestrator.prompt.mdDrop your defect intake as a file in jobs/0_new/, then run the orchestrator: it discovers the intake, runs its creation/bootstrap step to author the bug JOB.md from the preset, and advances the job through the lean pipeline to jobs/4_done/ in the same run — pausing only at the before_commit and before_pr Git gates.