Bugfix Lifecycle

RaiSE uses a structured bugfix pipeline: 10 phases orchestrated by the MCP pipeline engine, with human-in-the-loop gates at the review points that prevent cascading errors.

Why a Pipeline?¶

Bugs fail differently than features. A feature can be built incrementally; a bug fix that starts from the wrong root cause wastes the entire effort. The pipeline addresses this with gates at the critical decision points:

After scoping — Is this the right problem?
After analysis — Is this the right root cause and strategy?
After architecture review — Is the planned change proportionate?
After fixing — Does the fix actually work?
After quality review — Are semantic risks, regressions, and tests addressed?

Quick Start¶

Inside Claude Code, ask Rai to start the bugfix pipeline:

Start the bugfix pipeline for RAISE-251

Rai calls pipeline_start with pipeline: bugfix, detects which phase to start from (or resumes from where you left off), and pauses at each gate for your review.

Note: /rai-bugfix-run was removed in 3.0. Use the MCP pipeline engine instead. See Migrating from 2.x.

The 10 Phases¶

/rai-bugfix-start     → Reproduce, scope the bug
/rai-bugfix-triage    → Classify in 4 dimensions
                      ── GATE 1: Scope & Classification ──
/rai-bugfix-analyse   → Root cause analysis (5 Whys, Ishikawa, or direct)
                      ── GATE 2: Root Cause & Strategy ──
/rai-bugfix-plan      → Decompose fix into TDD tasks
/rai-architecture-review → Proportionality and design review
                      ── GATE 3: Architecture Review ──
/rai-bugfix-fix       → Execute fix with tests
                      ── GATE 4: Fix Verification ──
/rai-quality-review   → Semantic bugs, test quality, regressions
                      ── GATE 5: Quality Review ──
/rai-bugfix-review    → Retrospective, pattern extraction
/rai-bugfix-pir       → Optional post-incident review
/rai-bugfix-close     → Push branch, create MR, verify artifacts

Phase 1: Start¶

Creates work/bugs/RAISE-{N}/scope.md with reproduction steps, environment details, and expected vs actual behavior.

Phase 2: Triage¶

Classifies the bug in 4 dimensions:

Dimension	Values	Purpose
Bug Type	Logic, Data, Integration, Config, Regression, Performance	What kind of defect
Severity	Critical, High, Medium, Low	Impact on users
Origin	Design, Implementation, Environment, External	Where the defect was introduced
Qualifier	Flaky, Edge-case, Silent, Blocking, Cascading	Behavioral characteristic

Phase 3: Analyse¶

Root cause analysis using signal-driven method selection:

Direct — Cause is obvious from reproduction
5 Whys — Cause is not obvious, needs iterative questioning
Ishikawa — Multiple potential causes, needs systematic exploration

Produces analysis.md with root cause, evidence, and multiple fix approaches with trade-offs.

Phase 4: Plan¶

Decomposes the selected fix approach into atomic TDD tasks — each task has a test to write first (RED), implementation (GREEN), and optional refactor.

Phase 5: Architecture Review¶

Reviews the plan for proportionality, coupling, and architectural fit before implementation begins.

Phase 6: Fix¶

Executes the plan: write tests, implement fix, verify the bug no longer reproduces. Commits after each task.

Phase 7: Quality Review¶

Audits the fix for semantic bugs, regression risk, and meaningful test coverage.

Phase 8: Review¶

Retrospective: what caused the bug, what did we learn, are there patterns to extract? Produces retro.md and optionally adds patterns via rai pattern add.

Phase 9: PIR¶

Runs an optional post-incident review for severe incidents when the pipeline condition applies.

Phase 10: Close¶

Pushes the bug branch, creates a merge request, transitions Jira to Done, verifies all artifacts exist.

HITL Gates¶

Gates are mandatory — they cannot be skipped, even at Ri mastery level.

Gate 1: Scope & Classification¶

Presented after phases 1-2. You verify:

Is this the right problem?
Does the reproduction match what users reported?
Is the classification correct?

Responses: y (continue) · edit (correct scope/classification) · reject (stop)

Gate 2: Root Cause & Strategy¶

Presented after phase 3. This is the highest-value gate — it presents multiple fix approaches with trade-offs. Rai biases toward the simplest approach that fully addresses the root cause.

Fix approaches:
  A: Add gitignore entry for cache file — simple, 1 line
  B: Add cache validation + cleanup on startup — thorough, 40 LOC
  C: Redesign cache storage to use temp directory — most robust, 200 LOC

Recommended: A because the root cause is a missing gitignore entry

Responses: a/b/c (select approach) · adjust (refine strategy) · reject (re-analyse)

Gate 3: Architecture Review¶

Presented after phase 5. You verify:

The approach is proportionate to the bug
The design does not introduce unnecessary coupling
The plan still matches the selected strategy

Responses: y (continue to fix) · reject (revise plan or architecture)

Gate 4: Fix Verification¶

Presented after phase 6. You verify:

Tests pass
Bug no longer reproduces
Changed files look correct

Responses: y (continue to quality review) · reject (review code, identify issues)

Gate 5: Quality Review¶

Presented after phase 7. You verify:

The review found no unresolved semantic defects
Tests specify the regression clearly
Any follow-up risks are captured

Responses: y (continue to review + close) · reject (fix review findings)

Resume Support¶

The orchestrator detects existing artifacts and resumes from the most advanced phase. If a session is interrupted, ask Rai again: "Resume the bugfix pipeline for RAISE-251" — it calls pipeline_restore and picks up where you left off.

Using Individual Skills¶

Each phase is independently invocable for targeted work:

/rai-bugfix-triage      # Re-classify an already-scoped bug
/rai-bugfix-review      # Run retrospective on an already-fixed bug

Artifacts¶

All artifacts live in work/bugs/RAISE-{N}/:

File	Phase	Content
`scope.md`	start + triage	Reproduction, classification
`analysis.md`	analyse	Root cause, evidence, approaches
`plan.md`	plan	TDD task breakdown
`retro.md`	review	Retrospective, patterns