/enriching-roadmap

name: enriching-roadmap
description: Enriches implementation roadmap chunks with acceptance criteria, pattern references, and contextual notes. Use after decomposing-work has produced the structural roadmap and before planning-software creates the orchestration plan. Does not modify chunk structure or dependencies.

Enriching Roadmap

Enriches a confirmed structural roadmap so every chunk becomes self-contained enough for a developer-agent to begin work — adding acceptance criteria, pattern references, and contextual notes without modifying any structural field decomposing-work produced.

**Position:** decomposing-work (ROADMAP.md structural) → enriching-roadmap (acceptance criteria, pattern refs, notes) → planning-software (orchestration plan).

**Inputs:** confirmed ROADMAP.md; approved ARCHITECTURE.md (source for pattern references and component context); PRD.md (source of testable success criteria); workflow tier; optionally `.interface-design/system.md` — if present, derive design-specific acceptance criteria for UI chunks. If the tier was not specified, infer from the roadmap (1-3 chunks = Quick, 4-8 = Standard, 9+ or phased DAG = Thorough), state the inference, and proceed.

**Output:** the same ROADMAP.md, modified in place — three fields appended to each chunk (`Acceptance criteria`, `Pattern references`, `Contextual notes`). Do not alter existing fields (`Type`, `Component`, `Status`, `Size`, `Depends on`, `Files`, `Description`). Present the enriched roadmap for human review before treating it as the working baseline.

**Not covered:** chunk structure and dependencies (decomposing-work), plan creation (planning-software), technology-specific implementation guidance (developer-agent skills).

Workflow

Step 1: Read All Inputs

Read PRD.md, ARCHITECTURE.md, and ROADMAP.md fully before writing anything. Build a working map of: PRD success criteria; architecture components and their responsibilities; what chunk-001 (walking skeleton) established (the primary pattern reference for all subsequent chunks); and, Thorough only, which ADRs constrain which chunks.

Step 2: Determine Enrichment Depth

One tier across the entire roadmap — never mixed per chunk.

| Tier | Acceptance criteria | Pattern references | Contextual notes | |---|---|---|---| | **Quick** | Not invoked — orchestrating-software-dev skips enrichment for Quick. If invoked directly, 1-2 per chunk | Not invoked | Not invoked | | **Standard** | 2-4 per chunk — full coverage of chunk scope | Required — point to walking skeleton or prior chunks | Reference relevant ARCHITECTURE.md section | | **Thorough** | 3-5 per chunk — coverage + edge cases and error paths | Required — point to walking skeleton or most relevant prior chunk | ARCHITECTURE.md section + ADR references + cross-chunk integration notes where chunks interact |

Step 3: Enrich Each Chunk

Process in roadmap order (Phase 0 first).

**Acceptance criteria:**

• Derive each criterion from a specific PRD success condition or architecture constraint — not from the chunk description alone
• Testable form: "Given X, when Y, then Z" or a concrete assertion ("All endpoints return JSON with a consistent error envelope")
• Standard/Thorough: add criteria for error paths and integration points where they exist in the chunk scope

**Pattern references (Standard and Thorough):**

• Prefer chunk-001 (walking skeleton) if it established the relevant pattern; if a prior chunk set a more specific one, point there
• Reference concrete locations: "Follow the handler pattern at `src/api/handlers/health.ts`"
• If no pattern exists yet (greenfield, early phase): "No existing pattern — establish the pattern for subsequent chunks to follow"
• Point to the location only — no example code, no explanation of how the pattern works

**Contextual notes (Standard and Thorough):**

• Reference the governing section: "See ARCHITECTURE.md > Authentication > JWT Strategy"
• Thorough: add constraining ADRs ("Constrained by ADR-003 (stateless auth)") and cross-chunk integration flags ("Integrates with chunk-008 (email adapter) — confirm shared event schema before implementing")
• If system.md exists and the chunk touches UI: reference the design system and add design-specific acceptance criteria (e.g., "Spacing uses the 4px base grid", "Cards follow the card pattern in system.md")

Step 4: Validate Enrichment

• [ ] Every chunk has all three fields appended
• [ ] All acceptance criteria are testable assertions, not descriptions of what the code will do
• [ ] Pattern references point to existing code locations, not explanations
• [ ] No existing chunk field modified
• [ ] Depth consistent across all chunks
• [ ] Thorough cross-chunk notes reference chunk IDs, not vague descriptions

Fix gaps, then present to the human.

Templates

Append after the existing `Description` field — never between existing fields.

**Standard tier:**

**Acceptance criteria:**
- <Primary testable outcome>
- <Error path or boundary condition>
- <Integration assertion where relevant>

**Pattern references:**
- Follow the handler pattern at `<path>` (established in chunk-001)

**Contextual notes:**
- See ARCHITECTURE.md > <Section name>

**Thorough tier:**

**Acceptance criteria:**
- <Primary testable outcome>
- <Error path — invalid input or external failure>
- <Boundary condition>
- <Integration assertion>

**Pattern references:**
- Follow the adapter pattern at `<path>` (established in chunk-00N)

**Contextual notes:**
- See ARCHITECTURE.md > <Section name>
- Constrained by ADR-00N (<decision title>)
- Integrates with chunk-00N (<chunk title>) — <specific integration point to verify>

Edge Cases

**Walking skeleton has no prior patterns:** write "No existing pattern — chunk-001 establishes the foundational pattern. Subsequent chunks follow this structure." Acceptance criteria focus on the end-to-end traversal the skeleton must prove.

**PRD lacks success criteria