nw-bugfix

# 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 └─ /nw-deliver "fix-{bug-id}" — roadmap-based bugfix flow └─ Paradigm detection determines crafter (OOP or FP) └─ 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 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:** 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) 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 The crafter handles the TDD cycle (3-phase canon RED → GREEN → COMMIT per 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 delegates to `/nw-deliver`, which handles paradigm detection, DES enforcement, and rigor profile automatically.