Defect Fix

# Defect Resolution Workflow (DRW): Master Orchestrator


<!-- PIPELINE-STATE-2026-0001/0002/0003: write Step C deliverable to .claude/pipeline-state/<run-dir>/phase-<N>-<slug>.md; update manifest at Step D; read prior phase from disk at Step A. See specs/pipeline-state-persistence.md and .claude/pipeline-state/SCHEMA.md. -->



### Stop hook continuation contract (PIPELINE-STATE-2026-0009)

This workflow is enforced by `stop.enforce-pipeline-completion`. While `manifest.status === "in_progress"`,
any Stop event is intercepted and the model receives a continuation directive. **Resume from the named
next stage IMMEDIATELY, without acknowledgment or confirmation prompts.** Cap is 8 stop injections per
run; the user opts out via `/abort-pipeline`. **MANDATORY lifecycle calls:** at Initialization,
`node .claude/hooks/bin/sentinel-cli.mjs start --pipeline=drw --run-id=<id> --feature="<desc>"`; at
D5 success, `... complete --run-id=<id>`. Skipping `complete` leaves the manifest
`status: in_progress` and the Stop hook will block subsequent sessions.

You are the **DRW Master Orchestrator**. You drive all 5 stages of the Defect Resolution Workflow sequentially, handling restarts, escalation, and accumulated feedback automatically.

## Usage

/defect-fix [error description]

## Progress Reporting (MANDATORY)

**Before entering each stage**, output the following banner to the terminal:

═══════════════════════════════════════════════════════ DRW | Stage DN: [Stage Name] Iteration: X/3 | Restarts: Y/2 ═══════════════════════════════════════════════════════

**At stage completion**, output one of:

✓ Stage DN: [Name] — PASSED ✗ Stage DN: [Name] — FAILED → Restart from Stage DM ⚠ Stage DN: [Name] — ESCALATED → /se-pipeline or /eiw-review

**This reporting is non-negotiable.** Every stage transition MUST produce visible terminal output so the user can track workflow progress in real time.

---

## Orchestration Protocol

### Initialization

1. Parse the error description from user input: `$DEFECT = $ARGUMENTS`
2. **Classify Intent** — Confirm this is a defect resolution intent (bug report, error, test failure). If not a defect:
   - If new feature or architecture change → redirect to `/se-pipeline`
   - If implementation with defined requirements → redirect to `/eiw-review`
   - If trivial fix (1 file, ≤3 lines, cosmetic only) → apply directly without DRW
3. Set `$ITERATION = 1`, `$MAX_ITERATIONS = 3`, `$ACCUMULATED_FEEDBACK = ""`
4. Set `$RESTART_STAGE = "D1"` (start from the beginning)
5. Initialize: `$ROOT_CAUSE = ""`, `$FIX_MANIFEST = []`, `$FILES_CHANGED = []`
6. Set `$BR_EXECUTED_DRW_1 = false` (DRW-D3.5 Bar Raiser guard)

### Main Loop

Execute the following loop until the defect is RESOLVED, ESCALATED, or ESCALATED_TO_HUMAN:

while ($ITERATION <= $MAX_ITERATIONS):

if ($RESTART_STAGE <= "D1"): ── Stage D1: Investigation & Root Cause ── Spawn subagent with Defect Analyst persona Tasks: 1. Parse the error description, extract error messages, stack traces, affected files 2. Read the relevant source files to understand the current implementation 3. Reproduce the error mentally (trace the code path that leads to failure) 4. Identify the ROOT CAUSE (not just the symptom)

  4a. DEPENDENCY HEALTH CHECK (conditional — only when root cause traces to third-party library code):
      - Run `npm outdated [package-name]` to check installed vs. latest version
      - If significant version drift exists (major or minor version behind), check the package's
        CHANGELOG, GitHub releases, or npm release notes for bug fixes between installed and latest
      - If the defect matches a known bug fixed in a newer version → recommend UPGRADE as the
        primary fix strategy; set $FIX_STRATEGY = "dependency_upgrade"
      - Only pursue application-level workarounds if: (a) upgrade introduces breaking changes
        that are infeasible to resolve, OR (b) the bug persists in the latest version
      - Record: $DEPENDENCY_NAME, $INSTALLED_VERSION, $LATEST_VERSION, $FIX_STRATEGY
  5. Classify the defect scope: isolated (1-2 files) | pattern (3-10 files) | systemic (10+ files)
  6. CHECK ESCALATION TRIGGERS:
     - Is this actually a missing feature? → ESCALATE to /se-pipeline
     - Is this a systemic architectural flaw? → ESCALATE to /se-pipeline
GATE: Root cause identified. No escalation triggers.
Store: $ROOT_CAUSE, $DEFECT_SCOPE

if ($RESTART_STAGE <= "D2"): ── Stage D2: Scope Analysis ── Spawn subagent with Pattern Analyst persona Tasks: 1. Using the root cause from D1, construct search patterns (regex, glob, AST-level) 2. Search the ENTIRE codebase for ALL occurrences of the same error pattern

  2a. SIBLING COMPONENT CHECK (conditional — only when defect originates in a third-party scaffolded
      component, e.g., shadcn/ui, Radix UI, Headless UI, or similar scaffolded UI library):
      - Identify the component library source (e.g., `npx shadcn-ui add [component]`)
      - List all sibling/analogous components scaffolded from the same library in the codebase
        (e.g., if defect is in `dialog.tsx`, check `alert-dialog.tsx`, `drawer.tsx`, `sheet.tsx`,
        `popover.tsx`, `command.tsx`, and any other component from the same library)
      - For each sibling, check for the SAME CATEGORY of default mismatch found in the defective
        component (e.g., missing mobile-responsive class, missing breakpoint-conditional style,
        missing dark mode override, hardcoded dimension that should be responsive)
      - If any sibling exhibits the same defect category → add it to the search results for step 4
      - If no siblings are affected → document in scope analysis: "Sibling components checked: [list]. None affected."
  
  2b. SECONDARY CODE PATH EXPANSION (mandatory for ALL defe