nw-bugfix · diff

git:20260609.c723548 to git:20260611.3860ed5

13 added, 33 removed. Audit A to A.

---

name: nw-bugfix

description: "Bug fix workflow: root cause analysis → user review → regression test + fix via TDD"

user-invocable: true

argument-hint: '[bug-description] - Describe the defect observed'

---

# NW-BUGFIX: Defect Resolution Workflow

**Wave**: CROSS_WAVE

**Agents**: Rex (nw-troubleshooter) → selected crafter (OOP or FP per project paradigm)

## Overview

End-to-end bug fix pipeline: diagnose root cause, review findings with user, then deliver regression tests that fail with the bug and pass with the fix. Ensures every defect produces a test that prevents recurrence.

## Flow

```

INPUT: "{bug-description}"

│

├─ Phase 1: Root Cause Analysis (@nw-troubleshooter)

│ └─ /nw-root-why "{bug-description}"

│ └─ Output: RCA document with root cause chain + fix proposal

│

├─ Phase 2: User Review (INTERACTIVE — STOP here)

│ └─ Present RCA findings to user

│ └─ User confirms root cause + approves fix direction

│ └─ If user rejects → refine RCA or stop

│

- └─ Phase 3: Regression Test + Fix (branches on workflow.mode)

- └─ classic → /nw-deliver "fix-{bug-id}" — roadmap-based bugfix flow

- └─ atdd_pure → single carpaccio slice via the /nw-execute per-slice cycle

+ └─ Phase 3: Regression Test + Fix

+ └─ /nw-deliver "fix-{bug-id}" — roadmap-based bugfix flow

└─ Paradigm detection determines crafter (OOP or FP)

- └─ Both modes: regression test (RED) → fix (GREEN) → verify (COMMIT)

+ └─ Regression test (RED) → fix (GREEN) → verify (COMMIT)

```

## Execution Steps

### Phase 1: Root Cause Analysis

**Skill loading**: The troubleshooter loads its skills from `~/.claude/skills/nw-{skill}/SKILL.md`:

- `nw-five-whys-methodology` — core investigation methodology

- `nw-investigation-techniques` — systematic debugging patterns

- `nw-post-mortem-framework` — structured incident analysis

Invoke @nw-troubleshooter via Agent tool:

```

Execute *investigate-root-cause for the following defect:

{bug-description}

Configuration:

- investigation_depth: 5

- multi_causal: true

- evidence_required: true

Produce:

1. Root cause chain (5 Whys with evidence at each level)

2. Contributing factors

3. Proposed fix with specific code changes

4. Files affected

5. Risk assessment of the fix

```

After the troubleshooter returns, present findings to the user. Include:

- Root cause summary (1-2 sentences)

- Evidence chain

- Proposed fix

- Files to modify

- Risk level

**STOP and wait for user confirmation before proceeding to Phase 3.**

### Phase 2: User Review

Present the RCA findings and ask:

1. "Does this root cause match your understanding?"

2. "Do you approve the proposed fix direction?"

3. "Any additional constraints or context?"

If user rejects:

- Refine the RCA with additional context

- Or stop the workflow entirely

If user approves → proceed to Phase 3.

- ### Phase 3: Regression Test + Fix (branches on workflow.mode)

+ ### Phase 3: Regression Test + Fix

- Phase 3 reads `workflow.mode` from `.nwave/config.yaml` and dispatches the fix

- along one of two paths. Both paths share paradigm detection (reads project

- CLAUDE.md for `## Development Paradigm`), crafter selection (@nw-software-crafter

- for OOP, @nw-functional-software-crafter for FP), DES enforcement, and the rigor

- profile from `.nwave/des-config.json`.

+ Phase 3 dispatches the fix through the roadmap-based bugfix flow. It does

+ paradigm detection (reads project CLAUDE.md for `## Development Paradigm`),

+ crafter selection (@nw-software-crafter for OOP, @nw-functional-software-crafter

+ for FP), DES enforcement, and reads the rigor profile from

+ `.nwave/des-config.json`.

- **Preparation (both modes):**

+ **Preparation:**

1. Derive feature-id: `fix-{kebab-case-bug-summary}` (max 5 words)

2. Create `docs/feature/{feature-id}/deliver/` directory

3. Prepare RCA context from Phase 1 output (root cause, files affected, proposed fix)

- #### Mode `classic` — roadmap-based bugfix flow

- Under `workflow.mode: classic`, delegate to `/nw-deliver`:

+ Delegate to `/nw-deliver`:

```

/nw-deliver "fix-{bug-summary}"

```

The deliver orchestrator builds a minimal two-step roadmap:

**Step 01-01: Regression test (RED)**

- Write a test that reproduces the exact defect

- Test MUST fail against current code (proves the bug exists)

- Test location: `tests/regression/{component}/` or `tests/bugs/`

- Test name: `test_bug_{description}.py`

**Step 01-02: Fix implementation (GREEN)**

- Implement the minimal fix identified in RCA

- Run ALL tests — regression test must now PASS

- Existing tests must not regress

- #### Mode `atdd_pure` — single carpaccio slice, no roadmap

- Under `workflow.mode: atdd_pure` the bugfix is the canonical single carpaccio

- slice: there is no roadmap and no roadmap-step extraction. The defect's

- regression test IS the slice's acceptance test (regression AT green → fix →

- commit). Run it through the slice-04 roadmap-free spine via the per-slice

- `/nw-execute` lean cycle:

- ```

- /nw-execute "fix-{bug-summary}"

- ```

- The per-slice cycle drives the same RED → GREEN → COMMIT shape — write the

- failing regression AT, implement the minimal fix, commit — as one carpaccio

- slice rather than a two-step roadmap.

The crafter handles the TDD cycle (3-phase canon RED → GREEN → COMMIT per

- ADR-025, or legacy 5-phase PREPARE → RED_ACCEPTANCE → RED_UNIT → GREEN → COMMIT

- for pre-2026-05-07 audit-log replay) with DES monitoring in either mode.

+ ADR-025) with DES monitoring.

## Success Criteria

- [ ] Root cause identified with evidence at each causal level

- [ ] User reviewed and approved fix direction

- [ ] Regression test written that fails with the bug

- [ ] Fix implemented that makes the regression test pass

- [ ] All existing tests still pass (no regressions)

- [ ] Commit with conventional message: `fix(scope): description`

## Examples

### Example 1: Runtime crash

```

/nw-bugfix "DES hook crashes with FileNotFoundError when template schema is missing"

```

Phase 1: Rex traces to missing `step-tdd-cycle-schema.json` in plugin cache.

Phase 2: User confirms.

Phase 3: `/nw-deliver "fix-missing-template-schema"` → crafter writes `test_bug_missing_template_schema.py` (RED), adds fallback path resolution (GREEN), commits.

### Example 2: Silent failure

```

/nw-bugfix "Skills plugin reports success but installs zero files when source has nw-prefixed layout"

```

Phase 1: Rex traces to `is_public_skill()` returning False for all nw-prefixed names due to ownership map key mismatch.

Phase 2: User confirms.

Phase 3: `/nw-deliver "fix-ownership-map-keys"` → crafter writes regression test with nw-prefixed fixture (RED), fixes ownership map keys (GREEN), commits.

### Example 3: Functional project bug

```

/nw-bugfix "Pipeline composition breaks when filter predicate returns None"

```

Phase 1: Rex traces to missing None guard in compose() function.

Phase 2: User confirms.

Phase 3: `/nw-deliver "fix-compose-none-guard"` → paradigm detected as FP → @nw-functional-software-crafter writes property-based test (RED), adds None guard (GREEN), commits.

## Notes

- This command is for **known defects** (something is broken). For new features, use `/nw-deliver`.

- The regression test is the primary deliverable — it prevents the bug from recurring.

- Keep the fix minimal. Refactoring belongs in `/nw-refactor`, not here.

- If the RCA reveals a design flaw (not just a code bug), escalate to `/nw-design` before fixing.

- - Phase 3 branches on `workflow.mode`: `classic` delegates to `/nw-deliver`; `atdd_pure` runs a single carpaccio slice via the `/nw-execute` per-slice cycle. Both modes handle paradigm detection, DES enforcement, and rigor profile automatically.

+ - Phase 3 delegates to `/nw-deliver`, which handles paradigm detection, DES enforcement, and rigor profile automatically.