Nw Roadmap Design

Roadmap Design

Roadmap Principles

When this skill is loaded, these principles activate in addition to the agent's core principles:

• Measure before planning: Never create roadmap without quantitative baseline. Require timing breakdowns|impact rankings|target validation. Halt and request data when missing.
• Concise roadmaps: Step descriptions max 50 words, AC max 5 per step at max 30 words each. Bullets over prose. Assume expertise. Eliminate qualifiers/motivational text. Token efficiency compounds -- crafter reads roadmap ~35 times.
• Paradigm-aware roadmap strategy: When functional paradigm selected, adapt roadmap for FP: types-first (algebraic data types before implementation)|composition pipelines|pure core/effect shell|effect boundaries instead of port interfaces. Strategic guidance only -- no code snippets/function signatures.

Roadmap Critical Rules

• Never include implementation code in roadmaps. You design; software-crafter writes code.
• Never create roadmaps without quantitative data. Halt and request measurement data when missing.
• Roadmap steps with identical patterns (differing by substitution variable) must batch into single step. 3+ identical-pattern steps = batching opportunity.

Quality Gate (DELIVER only)

• [ ] Roadmap step count efficient (steps/production-files <= 2.5)

Canonical Format

Use ONLY compact nested format. See nWave/templates/roadmap-schema.json for fields/validation. Structure: roadmap metadata, phases with nested steps, implementation_scope, validation. Phase IDs: two digits ("01"). Step IDs: "NN-MM".

Concision Requirements

Token efficiency: crafter reads roadmap ~35 times (7 phases x 5 steps). 5000-token x 35 = 175k tokens. 1000-token x 35 = 35k (80% savings).

Quantitative Limits

• Step description: max 50 words | AC per step: max 5 | Each AC: max 30 words
• Step notes: max 100 words
• Target: small (1-3 steps) = 500, medium (4-8) = 1500, large (9-15) = 3000 tokens

Include

WHAT to build (one sentence) | WHY (brief business value) | Observable outcomes (testable AC) | Architectural constraints | Integration points

Exclude

HOW to implement | code snippets/class names | algorithm descriptions | step-by-step instructions | tech tutorials | testing strategy (TDD standard) | motivational language | redundancy | examples when description clear

Compression Techniques

Bullets over prose | eliminate qualifiers | assume expertise | active voice | omit obvious

Acceptance Criteria Abstraction

AC describe observable outcomes, never internal implementation.

Rules

Describe WHAT (behavior) not HOW (implementation) | Never reference private methods (underscore prefix) | Never reference internal class decomposition | Never prescribe signatures/params/return types | Crafter decides structure during GREEN + REFACTOR

Good AC Examples

• "DES module importable from installation target after install"
• "DES utility scripts present and executable in scripts directory"
• "Installation uses backup before overwriting existing components"

Bad AC Examples (implementation-coupled)

• "_install_des_module() copies src/des/ to ~/.claude/lib/python/des/"
• "verify() checks DES module importable via subprocess test"
• "context.installation_verifier._check_agents() called for verification"

Step Decomposition Efficiency

Step Ratio Check

Rule: steps_count / estimated_production_files <= 2.5

Violation = over-decomposition. Action: merge steps targeting same file.

Identical Pattern Detection

Rule: if N steps differ only by substitution variable, batch into 1 step. Threshold: 3+ identical-pattern steps must batch.

Bad: 4 separate steps for AgentsPlugin, CommandsPlugin, TemplatesPlugin, UtilitiesPlugin

Good: 1 step creating all 4

No-Op Prevention

Each step must add production code. Validation-only steps are not steps.

Bad: "Step 02-05: Validate extraction with integration tests"

Good: validation is part of preceding step's REVIEW phase

Step-to-Scenario Mapping

For roadmaps feeding DELIVER wave:

• Read acceptance tests (tests/acceptance/test_*.py) before creating roadmap
• Count scenarios (def test_*) | 3. ~1 step per scenario (flexibility for infra steps)
• Mark infra steps: "type: infrastructure" | 5. Principle: 1 Scenario = 1 Step = 1 TDD Cycle

For each step mapped to a distilled acceptance scenario, populate:

• test_file: relative path to the test file (e.g., tests/acceptance/test_auth.py)
• scenario_name: the scenario/test function name (e.g., test_login_with_valid_credentials)

These fields enable the crafter to locate and unskip the exact pre-existing test during RED (3-phase canon per ADR-025; legacy logs record the same activation under the RED_ACCEPTANCE sub-step).

If DISTILL was skipped, leave these fields empty — the crafter will write new tests.

Measure Before Plan Gate

Before any roadmap, verify: 1. Timing data shows WHERE time spent | 2. Impact ranking shows MOST contributing component | 3. Target validation provides evidence

Missing data: halt, request measurement, offer to help. Gate is blocking.

Simplest Solution Gate

Before multi-phase (>3 steps), document rejected alternatives:

Alternatives to Consider

• Configuration-only (no code) | 2. Single-file change | 3. Existing tool/library | 4. Partial (solve 80% simply)

Documentation Format

## Rejected Simple Alternatives

### Alternative 1: {simplest approach}
- What: {description}
- Expected Impact: {% of problem solved}
- Why Insufficient: {evidence-based reason}

### Why Complex Solution Necessary
1. Simple alternatives fail due to: {specific reason with evidence}
2. Complexity justified by: {benefit simple solutions cannot achieve}

Min 2 alternatives. Each: specific description, expected impact, evidence-based rejection.

Examples

Example 1: Roadmap Step (Correct)

Schema source-of-truth: nWave/templates/roadmap-schema.json (required step fields: id, name, criteria as list[str]).

{
  "id": "01-03",
  "name": "Order processing with payment integration",
  "criteria": [
    "Order confirmed after successful payment",
    "Failed payment returns clear error to caller",
    "Order persists with payment reference"
  ],
  "files_to_modify": [
    "src/order/application/order_service.py",
    "src/order/adapters/payment_gateway.py"
  ],
  "implementation_notes": "Payment gateway accessed through driven port; order aggregate maintains consistency."
}

Example 1b: Functional Paradigm (Correct)

{
  "id": "01-03",
  "name": "Order processing pipeline with payment integration",
  "criteria": [
    "Valid order request produces confirmed order with payment reference",
    "Invalid payment produces domain error value (not exception)",
    "Order state is immutable — processing produces new OrderConfirmed value"
  ],
  "files_to_modify": [
    "src/order/pipeline.py",
    "src/order/payment_port.py"
  ],
  "implementation_notes": "Payment accessed through function-signature port (PaymentRequest -> Result); pipeline composed from pure transformations; effect boundary at adapter layer only."
}

Same WHAT-level criteria as Example 1, adapted for FP. No function names or type definitions -- functional-software-crafter decides those.

Example 2: Roadmap Step (Incorrect -- Implementation Coupled)

{
  "id": "01-03",
  "name": "Implement PaymentProcessor class",
  "criteria": [
    "_validate_card() returns CardValidationResult",
    "PaymentProcessor.charge() uses retry with exponential backoff"
  ]
}

Crafter decides class names|method signatures|retry strategies.