Task: Generate roadmap/-/ROADMAP.md — Planned-Work Trigger

Task: Generate roadmap/<NNN>-<slug>/ROADMAP.md — Planned-Work Trigger

Objective

Produce one roadmap/<NNN>-<slug>/ROADMAP.md file per invocation that files a single planned-work trigger — a feature, refinement, refactor, or chore — into the project's roadmap. The skill is one of two trigger-creation skills (the other is /ISSUE.md for defects in shipped code); the /ROADMAP.md and /ISSUE.md artifacts are the only way work enters phase G of the Agent-Driven Development pipeline. The output carries enough verifiable acceptance criteria for the downstream /SPEC.md (G1) to scope a unit, for /SPEC_REVIEW.md (G2) to validate scope alignment, and for /VERIFICATION.md (G7) to confirm the unit fulfilled the trigger. Frontmatter is mutable — orchestrator and /RECONCILIATION.md (G8) advance status and populate promoted_to_units over the trigger's lifecycle. The body is largely write-once: regenerate only when the user explicitly asks to refine.

ROADMAP exists because every code change in ADD must originate from a durable, citable artifact — not a chat message, not an inline TODO. Without it, units are created on premises that disappear once the conversation that produced them ends, and /VERIFICATION.md has nothing to verify against. The defining discipline — and the commonest violation — is why / what / when-it's-done, never how: roadmap items must not contain wire formats, schemas, function signatures, code, or step-by-step plans. Those are the territory of SPEC, INTERFACES, DATA, IMPLEMENTATION, and PLAN respectively.

Inputs

1. User intent (required, primary subject) — free-text description of what should be filed. May include the kind hint ("feature", "refactor", "chore", "refinement"), the area hint, the priority hint, and the rough description. Extract these from the prose if not stated explicitly.
2. PROPOSAL.md (required, auto-discovered at project root) — for principles, non-goals, scope boundaries, and target actors. The roadmap item must not contradict any.
3. ARCHITECTURE.md (required, auto-discovered at project root) — for component topology and to identify which component owns the work.
4. DOMAIN.md (required, auto-discovered at project root) — for the bounded-context catalog, which is the source of valid area: values.
5. Existing roadmap items (auto-discovered) — roadmap/*/ROADMAP.md. Used for <NNN> allocation and for detecting overlapping items.
6. Existing issues (auto-discovered) — issues/*/ISSUE.md. Frontmatter scan only. Used for cross-references when the new roadmap item closes or supersedes existing issues.
7. Existing units (auto-discovered) — units/*/u*/SPEC.md. Frontmatter scan plus a one-line concept summary. Used for detecting overlap with shipped or in-flight work and for populating Current state.
8. Surface IAs and contract artifacts (optional, selectively read) — WEB_IA.md, CLI_IA.md, INTERFACES.md, DATA.md, BEHAVIOR.md, ERRORS.md, QUALITY.md, SECURITY.md, OPERATIONS.md. Read selectively when discovery suggests the feature touches a particular surface or contract layer.
9. Existing roadmap/<NNN>-<slug>/ROADMAP.md (auto-discovered — only if refining) — when the user asks to refine an existing roadmap item, read it fully and preserve the orchestrator-managed frontmatter fields (id, slug, status, promoted_to_units).

Read budget: 3 required full reads (PROPOSAL, ARCHITECTURE, DOMAIN) + 2–4 frontmatter-only scans (cheap — YAML headers only) + 1–3 selective full reads of design artifacts the discovery surfaces. Within ADD's bounded read-set principle (≤ 10 reads).

Workflow

Roadmap filing proceeds in six phases: intent extraction, discovery, body authoring, ID allocation and frontmatter, validation, and write. Phases are sequential; revisit earlier phases if a later one reveals a missing concept, an overlap, or a contradiction.

Phase 1: Intent Extraction

Read the user intent end-to-end. Extract five things into a working note:

• Kind: feature | refinement | refactor | chore. If unstated, infer from the prose. A "new capability for users" is a feature. "Improve the simplification we made in u012" is a refinement. "Restructure module X internally" is a refactor. "Upgrade dependency Y" is a chore. When the prose mixes signals (e.g., "let's clean up the validation and add per-field rules"), treat it as two distinct triggers — file the dominant one and surface the second in Open Questions for follow-up.
• Area: must be one of the bounded contexts in DOMAIN.md § 2. If the user named it, use that. Otherwise infer from the concepts and components implied by the intent. If the work straddles two areas equally, the work is over-scoped — see Rule 5; surface in Open Questions.
• Priority: low | medium | high. If unstated, default to medium.
• Title: a short descriptive phrase. Becomes the title: field and seeds the slug.
• Concept keywords: 3–8 nouns and verbs that name the feature concept. These drive Phase 2 discovery — be generous; over-keyword is cheaper than under-keyword.