roadmap-updater

roadmap-updater

Overview

Maintain ROADMAP.md as the canonical deterministic task lifecycle artifact. This skill converts approved work into explicit roadmap checkpoints and tracks status progression without losing decision context.

When to Use

• Use when approved work must be translated into roadmap checkpoints or status updates.
• Use when reconciling roadmap state with implementation evidence.
• Don't use for ad-hoc task lists — the roadmap is the canonical lifecycle surface.

Required behavior

1. Convert approved work into explicit roadmap checkpoints.
2. Update status progression without losing prior decision context.
3. Keep entries concise, actionable, and traceable to implementation evidence.
4. Flag contradictions between roadmap state and manifest/runtime state.
5. Staging gate: When doc audits or cleanup surface candidate items NOT explicitly requested by the user, stage them in a document (e.g., docs/potential-roadmap-items.md) for user review. Do NOT add them directly to ROADMAP.md.
6. Verify before adding: When pulling items from deleted planning docs, research reports, or review reports, check the actual source code to confirm the item was NOT already implemented. Stale planning docs often describe work that was completed but the doc was never deleted.

Status transitions

The roadmap tracks work through these states:

• Not Started — Approved but not yet begun
• In Research — Discovery phase underway
• In Planning — Plan being developed (includes innovate checkpoint)
• In Execution — Implementation in progress
• Ready for Review — Execution complete, awaiting reviewer-agent
• Complete — Review passed, user confirmed, validation evidence present

Agents may move work to Ready for Review but must not mark Complete unless:

1. Explicit user confirmation is received, AND
2. Validation evidence required by quality policy is present

Guardrails

• Avoid creating duplicate task systems — ROADMAP.md is the canonical lifecycle surface.
• Preserve chronological auditability of updates.
• Escalate unresolved blockers instead of masking them.
• Staging gate: Candidate items discovered during doc cleanup or audits that are NOT explicit user requests go to a staging document (e.g., docs/potential-roadmap-items.md) for user review. Do NOT add them to ROADMAP.md until approved.
• Verify before adding: When pulling items from deleted planning docs or research reports, check the actual source code to confirm the item was NOT already implemented. Stale planning docs often describe completed work.