# Root Cause Analysis: Solution Architect Generates Roadmap During DESIGN Wave

**Date**: 2026-03-06
**Investigator**: Rex (nw-troubleshooter)
**Methodology**: Toyota 5 Whys
**Status**: Complete -- actionable fixes identified

---

## Problem Statement

The `nw-solution-architect` agent creates a `roadmap.json` file during the DESIGN wave (`/nw:design`). This is incorrect. The roadmap (implementation plan with steps, acceptance criteria, and files_to_modify) is a DELIVER wave artifact that should only be created during `/nw:deliver` by delegating to the solution architect via `/nw:roadmap`. The DESIGN wave should produce architecture documents (C4 diagrams, technology selection, component boundaries, ADRs) only.

**Impact**: Recurring issue observed multiple times. Creates confusion about wave boundaries, produces premature implementation planning before architecture review, and pollutes the design artifacts directory with deliver-phase content.

**Scope**: Agent definition, command definition, and skill files for the solution architect within the nWave framework.

---

## Evidence Summary

### E1: Agent definition explicitly lists `roadmap-design` as a core skill

**File**: `nWave/agents/nw-solution-architect.md`, line 15
```yaml
skills:
  - architecture-patterns
  - architectural-styles-tradeoffs
  - security-by-design
  - domain-driven-design
  - formal-verification-tlaplus
  - stress-analysis
  - critique-dimensions
  - roadmap-design           # <-- HERE
```

### E2: Agent core principles contain THREE roadmap-focused principles

**File**: `nWave/agents/nw-solution-architect.md`, lines 33, 36, 40
- Principle 4: "**Measure before planning**: Never create roadmap without quantitative baseline."
- Principle 7: "**Concise roadmaps**: Step descriptions max 50 words, AC max 5 per step..."
- Principle 11: "**Paradigm-aware roadmap strategy**: When functional paradigm selected, adapt roadmap for FP..."

Three of the agent's eleven core principles (27%) are dedicated to roadmap creation.

### E3: Agent Phase 4 always loads `roadmap-design` skill

**File**: `nWave/agents/nw-solution-architect.md`, lines 60, 77
```
| 4 Architecture Design | `roadmap-design` | Always — step decomposition and concision checks |
```
And: "Load: `architecture-patterns`, `roadmap-design` -- read both NOW before proceeding."

### E4: Agent quality gates include roadmap-specific metrics

**File**: `nWave/agents/nw-solution-architect.md`, line 157
```
- [ ] Roadmap step count efficient (steps/production-files <= 2.5)
- [ ] AC behavioral, not implementation-coupled
```

### E5: Agent examples show roadmap step YAML, not architecture artifacts

**File**: `nWave/agents/nw-solution-architect.md`, lines 163-203
Examples 1, 1b, and 2 all show `step_03` YAML with `title`, `description`, `acceptance_criteria`, and `architectural_constraints` -- these are roadmap step formats, not architecture document formats.

### E6: Agent critical rules mention roadmaps

**File**: `nWave/agents/nw-solution-architect.md`, lines 236-237
- Rule 1: "Never include implementation code in roadmaps/architecture documents."
- Rule 2: "Never create roadmaps without quantitative data."

### E7: DESIGN command tells agent to load `roadmap-design` skill

**File**: `nWave/tasks/nw/design.md`, line 95
```
**SKILL_LOADING**: Read your skill files at `~/.claude/skills/nw/solution-architect/`.
At Phase 4, always load: architecture-patterns.md, architectural-styles-tradeoffs.md,
roadmap-design.md.
```

### E8: DESIGN command expected outputs contain NO roadmap

**File**: `nWave/tasks/nw/design.md`, lines 118-127
```
docs/feature/{feature-id}/design/
  architecture-design.md       (includes C4 diagrams in Mermaid)
  technology-stack.md
  component-boundaries.md
  data-models.md
docs/adrs/
  ADR-NNN-*.md
```
No `roadmap.json` listed. The command correctly defines design-only outputs.

### E9: DELIVER command explicitly assigns roadmap creation to solution architect

**File**: `nWave/tasks/nw/deliver.md`, lines 82-85
```
2. Phase 1 -- Roadmap Creation + Review
   a. Skip if docs/feature/{feature-id}/deliver/roadmap.json exists
   b. @nw-solution-architect creates roadmap.json (read ~/.claude/commands/nw/roadmap.md)
```

### E10: DELIVER command includes a safety check for misplaced roadmaps

**File**: `nWave/tasks/nw/deliver.md`, lines 83-84
```
IMPORTANT: Only check the deliver/ subdirectory. If roadmap.json is found in design/ instead,
MOVE it to deliver/ and log warning: "Roadmap relocated from design/ to deliver/ — was created in wrong wave."
```
This evidence proves the problem has been observed before -- a workaround was added instead of a root cause fix.

### E11: `roadmap-design` skill contains implementation planning knowledge

**File**: `nWave/skills/solution-architect/roadmap-design.md`
The entire skill is about creating implementation roadmaps: step decomposition, AC writing, step-to-scenario mapping, concision requirements. This is exclusively DELIVER wave knowledge.

---

## Toyota 5 Whys Analysis

### Branch A: Agent definition teaches roadmap creation as core competency

```
WHY 1A: Solution architect creates roadmap.json during DESIGN wave.
  [Evidence: E10 -- deliver.md workaround proves this occurs; user reports recurring]

WHY 2A: The agent has extensive roadmap creation knowledge embedded in its definition.
  [Evidence: E1 -- roadmap-design skill listed; E2 -- 3/11 core principles about roadmaps;
   E4 -- quality gates for roadmaps; E5 -- examples show roadmap YAML]

WHY 3A: The agent's skill loading table loads roadmap-design in Phase 4 (Architecture Design)
  as "Always" trigger, making it an inseparable part of architecture work.
  [Evidence: E3 -- skill loading table marks roadmap-design as "Always" during Phase 4]

WHY 4A: The agent was designed to serve TWO roles: architect (DESIGN wave) and roadmap
  planner (DELIVER wave), with no mechanism to distinguish which role is active.
  [Evidence: E9 -- deliver.md explicitly uses solution-architect for roadmap creation;
   agent definition merges both responsibilities without wave-awareness]

WHY 5A: ROOT CAUSE -- The solution architect's definition conflates two distinct
  responsibilities (architecture design and implementation roadmap planning) into a
  single undifferentiated agent, with no wave-context gating mechanism.
  [Evidence: The agent file contains no conditional logic, phase gates, or wave-awareness
   that would suppress roadmap behavior when invoked for DESIGN versus DELIVER]
```

### Branch B: DESIGN command reinforces roadmap loading

```
WHY 1B: When invoked via /nw:design, the agent loads roadmap-design skill.
  [Evidence: E7 -- design.md SKILL_LOADING tells agent to load roadmap-design.md]

WHY 2B: The DESIGN command's SKILL_LOADING section explicitly lists roadmap-design
  alongside architecture-patterns and architectural-styles-tradeoffs.
  [Evidence: E7 -- "At Phase 4, always load: architecture-patterns.md,
   architectural-styles-tradeoffs.md, roadmap-design.md"]

WHY 3B: Once loaded, roadmap-design skill activates roadmap creation behavior:
  step decomposition, AC writing, step-to-scenario mapping, concision rules.
  [Evidence: E11 -- the skill file is 100% about implementation roadmap creation]

WHY 4B: There is no distinction in the DESIGN command between "learn about roadmap
  quality for future reference" and "create a roadmap now."
  [Evidence: E8 -- DESIGN expected outputs correctly exclude roadmap, but skill
   loading contradicts this by injecting roadmap creation knowledge]

WHY 5B: ROOT CAUSE -- The DESIGN command instructs the agent to load a skill
  (roadmap-design) that belongs exclusively to the DELIVER wave, creating a
  direct contradiction between expected outputs (no roadmap) and loaded knowledge
  (how to create roadmaps).
  [Evidence: E7 vs E8 -- skill loading includes roadmap-design, expected outputs exclude it]
```

### Branch C: No explicit prohibition exists

```
WHY 1C: The agent creates a roadmap even though the expected outputs do not list one.
  [Evidence: E8 -- design.md outputs have no roadmap; E10 -- but the workaround
   proves roadmaps appear in design/ anyway]

WHY 2C: The agent's constraints section does not prohibit roadmap creation during DESIGN.
  [Evidence: nw-solution-architect.md lines 245-248 -- constraints say "Designs
   architecture and creates documents only" and "Artifacts limited to docs/architecture/
   and docs/adrs/" but no explicit "do not create roadmap.json"]

WHY 3C: The agent has no wave-awareness: it does not know whether it was invoked
  for DESIGN (/nw:design) or DELIVER (/nw:roadmap or /nw:deliver).
  [Evidence: Agent definition has zero references to wave context; no conditional
   behavior based on invocation source]

WHY 4C: The wave methodology relies on command files to scope agent behavior, but the
  agent's own definition overrides this scoping by baking in roadmap competency.
  [Evidence: The agent treats roadmap creation as an intrinsic capability regardless
   of which command invoked it]

WHY 5C: ROOT CAUSE -- The agent definition lacks an explicit negative constraint
  ("never create roadmap.json during DESIGN wave") and has no wave-context
  awareness to conditionally enable/disable capabilities based on invocation source.
  [Evidence: Constraints section (lines 245-248) lists what the agent does, not
   what it must NOT do in specific wave contexts]
```

---

## Cross-Validation

| Root Cause | Explains Symptom? | Independently Verifiable? |
|------------|-------------------|---------------------------|
| A: Two roles conflated in one agent without wave gating | Yes -- agent always has roadmap knowledge, always uses it | Yes -- read agent definition |
| B: DESIGN command loads roadmap-design skill | Yes -- even if agent were neutral, command injects roadmap knowledge | Yes -- read design.md line 95 |
| C: No explicit prohibition or wave-awareness | Yes -- nothing stops the agent from acting on its knowledge | Yes -- search agent constraints section |

All three root causes are consistent and non-contradictory. They are complementary:
- A provides the capability (roadmap knowledge baked into the agent)
- B activates the capability during DESIGN wave (skill loading)
- C fails to prevent the behavior (no guardrail)

Together they fully explain the recurring symptom.

---

## Recommended Fixes

### Fix 1: Remove `roadmap-design` from DESIGN command skill loading [ROOT CAUSE B]

**Type**: Permanent fix (prevents recurrence)
**Priority**: P1 -- current sprint
**File**: `nWave/tasks/nw/design.md`, line 95

**Before**:
```
**SKILL_LOADING**: Read your skill files at `~/.claude/skills/nw/solution-architect/`.
At Phase 4, always load: architecture-patterns.md, architectural-styles-tradeoffs.md,
roadmap-design.md.
```

**After**:
```
**SKILL_LOADING**: Read your skill files at `~/.claude/skills/nw/solution-architect/`.
At Phase 4, always load: architecture-patterns.md, architectural-styles-tradeoffs.md.
Do NOT load roadmap-design.md during DESIGN wave -- roadmap creation belongs to the DELIVER wave (/nw:roadmap or /nw:deliver).
```

### Fix 2: Remove roadmap-design from agent's Phase 4 skill loading table [ROOT CAUSE A]

**Type**: Permanent fix (prevents recurrence)
**Priority**: P1 -- current sprint
**File**: `nWave/agents/nw-solution-architect.md`, lines 60 and 77

**Change the skill loading table**: Remove `roadmap-design` from Phase 4 "Always" trigger. Add a new row for roadmap-design triggered only when invoked via `/nw:roadmap` or `/nw:deliver`:

**Before** (line 60):
```
| 4 Architecture Design | `roadmap-design` | Always — step decomposition and concision checks |
```

**After**:
```
| Roadmap (DELIVER only) | `roadmap-design` | Only when invoked via /nw:roadmap or /nw:deliver — never during DESIGN wave |
```

**Before** (line 77):
```
Load: `architecture-patterns`, `roadmap-design` — read both NOW before proceeding.
```

**After**:
```
Load: `architecture-patterns` — read it NOW before proceeding.
```

### Fix 3: Add explicit negative constraint to agent definition [ROOT CAUSE C]

**Type**: Permanent fix (guardrail)
**Priority**: P1 -- current sprint
**File**: `nWave/agents/nw-solution-architect.md`, Constraints section (line 245-248)

**Add** after existing constraints:
```
- Does not create roadmap.json during DESIGN wave. Roadmap creation belongs exclusively to DELIVER wave via /nw:roadmap or /nw:deliver.
```

### Fix 4: Remove roadmap-specific quality gates from agent definition [ROOT CAUSE A]

**Type**: Permanent fix (removes misleading guidance)
**Priority**: P2 -- next sprint
**File**: `nWave/agents/nw-solution-architect.md`, Quality Gates section (line 157)

**Remove**:
```
- [ ] Roadmap step count efficient (steps/production-files <= 2.5)
```

This quality gate should only appear in the `/nw:roadmap` command context, not in the agent's general quality gates that apply during DESIGN wave.

### Fix 5: Scope roadmap-related core principles to DELIVER context [ROOT CAUSE A]

**Type**: Permanent fix (prevents knowledge leakage)
**Priority**: P2 -- next sprint
**File**: `nWave/agents/nw-solution-architect.md`, Core Principles section

Principles 4, 7, and 11 are roadmap-specific. Either:
- (a) Move them to a "DELIVER-Only Principles" subsection with a clear note that they apply only when invoked via `/nw:roadmap` or `/nw:deliver`, or
- (b) Move them into the `roadmap-design` skill file itself, so they are only active when the skill is loaded

Option (b) is preferred: it leverages the existing skill loading mechanism to conditionally activate roadmap behavior.

### Fix 6: Remove the deliver.md workaround [SYMPTOM TREATMENT]

**Type**: Cleanup (remove band-aid after root cause fixed)
**Priority**: P3 -- after fixes 1-3 verified
**File**: `nWave/tasks/nw/deliver.md`, lines 83-84

**Remove**:
```
IMPORTANT: Only check the deliver/ subdirectory. If roadmap.json is found in design/ instead,
MOVE it to deliver/ and log warning: "Roadmap relocated from design/ to deliver/ — was created in wrong wave."
```

This workaround masks the root cause. After fixes 1-3, roadmaps should never appear in `design/`. Keep for one release cycle as a safety net, then remove.

---

## Fix Priority Summary

| Priority | Fix | Root Cause | Effort |
|----------|-----|------------|--------|
| P1 | Fix 1: Remove roadmap-design from DESIGN command skill loading | B | 5 min |
| P1 | Fix 2: Remove roadmap-design from agent Phase 4 skill table | A | 5 min |
| P1 | Fix 3: Add explicit negative constraint | C | 2 min |
| P2 | Fix 4: Remove roadmap quality gate from general gates | A | 2 min |
| P2 | Fix 5: Scope roadmap principles to DELIVER context | A | 15 min |
| P3 | Fix 6: Remove deliver.md workaround (after fixes verified) | -- | 2 min |

---

## Validation Plan

After implementing P1 fixes (1-3):
1. Invoke `/nw:design` for a test feature and verify the agent does NOT create roadmap.json
2. Invoke `/nw:deliver` for the same feature and verify the agent DOES create roadmap.json via `/nw:roadmap`
3. Verify the agent loads `roadmap-design` skill only when invoked through DELIVER path

After implementing P2 fixes (4-5):
4. Verify agent quality gates during DESIGN wave do not reference roadmap metrics
5. Verify roadmap principles are active only when `roadmap-design` skill is loaded
