--- name: roadmap description: > ยท Capture and prioritize feature ideas and competitor findings in a private ROADMAP.md backlog. license: MIT compatibility: "Requires git. Optional: gh (GitHub CLI) or glab (GitLab CLI) for PR tracking and competitive scanning" metadata: source: iuliandita/skills date_added: "2026-04-05" effort: medium argument_hint: "[ideas... | update | scan | review]" --- # Roadmap: Lightweight Project Idea Tracker Manage a project's feature backlog in a gitignored ROADMAP.md. Quick idea capture, progress tracking after PRs and releases, competitive intelligence from similar repos, and periodic review to keep priorities honest. Not a project management system. No phases, no execution plans, no milestones. Just a scratchpad that evolves with the project. ## When to use - Capturing feature ideas, brainstorms, or "what if" thoughts for a project - Tracking which ideas shipped via PRs or releases - Scanning competing or similar repos for feature inspiration - Reviewing and prioritizing the idea backlog - Bootstrapping a fresh ROADMAP.md for a project that doesn't have one - User says "add to roadmap", "what should I build next", or "what are competitors doing" ## When NOT to use - Structured project management with phases, milestones, execution plans - Sprint or iteration planning with task dependencies - Code review or PR review - use **code-review** - Writing project docs or READMEs - use **update-docs** - Factual drift in `ROADMAP.md` itself (stated version mismatch, shipped highlights out of date, `[planned]` / `[exploring]` items that already shipped) - use **update-docs**. This skill owns prioritisation and idea capture; update-docs owns keeping the file's stated facts honest. - Tracking bugs or incidents - use issue trackers directly --- ## AI Self-Check Before writing or modifying ROADMAP.md, verify: - [ ] **Gitignored**: ROADMAP.md is in .gitignore (or user explicitly opted out of gitignoring) - [ ] **No secrets**: entries don't contain API keys, internal URLs, or sensitive business info - [ ] **Attribution preserved**: competitive intel cites the source repo or project - [ ] **No duplicates**: new ideas don't repeat existing entries (check intent, not just wording) - [ ] **Format preserved**: edits work within the existing file structure - don't reformat sections the user didn't ask to change - [ ] **Shipped items attributed**: completed entries reference the PR, release, or commit - [ ] **No hallucinated competitive data**: every feature, issue count, or user demand claim from a competitor repo is backed by an actual link or quote - not inferred - [ ] **No priority inflation**: P0 items are genuine blockers, not aspirational wishes - [ ] **Evidence quality marked**: competitive intel, user feedback, and assumptions are labeled with source and confidence - [ ] **Backlog hygiene kept**: stale ideas are parked or deleted instead of endlessly reprioritized - [ ] Cross-cutting agent hygiene applied - see `references/agent-hygiene.md` ## Roadmap Format ### Sections (fixed order) Every ROADMAP.md uses these sections in this order. Empty sections can be omitted but the order is not negotiable - consistency makes the file scannable. When adding content to a previously omitted section, create it in the canonical position relative to existing sections. ```markdown # Roadmap > Project: {name} | Updated: {date} | Current: v{version} > Local planning doc, gitignored. Not a commitment. ## Snapshot {1-2 paragraphs: project state, what the next milestone means, current focus} ## Exit Criteria What "done" means for the next milestone. Each criterion has a verdict. ### {Criterion Name} **Verdict**: Pass | Fail | Partial - {Requirement} - {Requirement} ## Now - P0 Blocks the next milestone or release. Active work only. - [in-progress] {Description} - {area} | PR #{n} - [planned] {Description} - {area} ## Next - P1 Committed direction. Happens after Now is clear. - [planned] {Description} - {area} - [exploring] {Description} - {area} ## Later - P2 Good ideas, no timeline. Revisit during review. - {Description} - {context} ## Experiments Low confidence. Build only with real demand signal. - {Description} - {what would validate it} ## Shipped ### v{X.Y.Z} ({date}) - ~~{Description}~~ - {area} | PR #{n}, v{X.Y.Z} ({date}) ## Competitive Intel ### {owner/repo} - {Feature} ({relevant | weak signal | noise}) - {evidence} - User demand: {issue links, discussion quotes, vote counts} ## Parked Items deferred with reason. - {Description} - {reason for parking} ``` ### Item format Items have two tiers depending on where they live: **Active items (Now, Next)** - structured, with status and tracking: ``` - [status] Description - area | tracking ``` Status values: `exploring`, `planned`, `in-progress` Area values are project-specific shorthand for the component or domain (e.g., `ui`, `api`, `backend`, `infra`, `docs`, `auth`). Infer from the project's structure. If unclear, omit the area rather than guessing. **Backlog items (Later, Experiments)** - lightweight, quick capture: ``` - Description - context or source ``` Items gain structure as they're promoted. A quick idea in Later becomes a tracked item when it moves to Next. **Shipped items** always get attribution: ``` - ~~Description~~ - area | PR #N (or MR #N), vX.Y.Z (date) ``` ### When a ROADMAP.md already exists Read the existing structure first. If it doesn't match this format: - In **add** or **update** modes: work within the existing structure, don't restructure - In **review** mode: suggest migrating to this format if the current one is disorganized - If the user asks to restructure: migrate section by section, preserving all content --- ## Performance - Keep roadmap edits small and frequent; avoid rewriting the whole backlog for one new idea. - Limit active P0/P1 items so prioritization remains meaningful. - Group duplicate ideas and link evidence instead of copying long notes repeatedly. --- ## Best Practices - Tie each near-term item to a clear user, business, or technical outcome. - Record exit criteria before implementation starts. - Separate commitments from experiments so speculative work does not crowd delivery. --- ## Workflow ### Step 0: Activity Detection (runs on every invocation) If no ROADMAP.md exists yet or a successful activity query returns no recent activity, skip the reminder. Report query failures as unavailable evidence. Otherwise, check for recent project activity: ```bash # Detect forge CLI: gh (GitHub), glab (GitLab), or git-only fallback # GitHub gh pr list --state merged --limit 10 \ --json number,title,mergedAt # GitLab glab mr list --merged --per-page 10 # Always available (portable - no GNU date required) git tag --sort=-creatordate | head -5 git log --oneline --since="2 weeks ago" | head -15 ``` If neither `gh` nor `glab` is available, note it once ("PR tracking unavailable - install gh or glab for full coverage") and continue with git-only data (tags + commits). If merged PRs or new releases look like they match open roadmap items, mention it briefly before proceeding: > "Heads up: PR #142 and v0.15.0 landed since the last roadmap update. > Want me to check those off first, or continue with {requested mode}?" Don't block. If the user ignores it, proceed with their request. --- ### Mode 1: Add Ideas (default) Trigger: user throws ideas at the project, says "add to roadmap", or describes features. #### Step 1: Bootstrap if needed 1. Check if ROADMAP.md exists in the project root (in monorepos, default to the git root unless the user specifies a package - if multiple ROADMAP.md files exist, ask) 2. Before writing any content, ensure /ROADMAP.md is ignored unless the user explicitly opted into tracking. If needed, add: ``` # Project roadmap (local planning doc) /ROADMAP.md ``` Verify with `git check-ignore --no-index ROADMAP.md` and check `git ls-files --error-unmatch ROADMAP.md`: an already tracked file remains tracked despite ignore rules; do not silently untrack it. 3. If absent, create it using the starter structure. Read README or the primary manifest to fill Snapshot with real context. Report any ignore entry added. #### Step 2: Parse and place ideas Extract actionable items from the user's input. For each idea: - Write a clear, concise description (keep the user's voice - clean up only if unclear) - Place it in the right priority tier (ask if genuinely ambiguous, default to P1) - Add context: where the idea came from, what it enables, any constraints mentioned Append to the appropriate section. Don't reorder existing items. #### Step 3: Offer competitive scan If the roadmap has no competitive intel section and this is the first batch of ideas, ask: > "Want me to scan similar repos for feature ideas that might fit {project-name}?" Ask once per session. If declined, don't ask again. --- ### Mode 2: Update / Check Off Trigger: user says "update roadmap", asks to check off items, or after a PR merge / release. If no ROADMAP.md exists, redirect to Mode 1 (bootstrap) first. #### Step 1: Gather recent activity ```bash # Always available (portable - no GNU date required) git log --oneline --since="2 weeks ago" git tag --sort=-creatordate | head -5 # GitHub gh pr list --state merged --limit 20 \ --json title,number,mergedAt # GitLab glab mr list --merged --per-page 20 ``` Adjust the time range if the user specifies one. If the user names specific PRs directly (e.g., "PR #45"), fetch those with `gh pr view 45 --json title,mergedAt` (or `glab mr view 45`) instead of relying on the time-windowed list. #### Step 2: Match activity to roadmap items Compare commit messages, PR titles, and release notes against open roadmap items. Use semantic matching - "add dark mode support" matches "Dark mode theme option". Present matches to the user before making changes: > Found these potential matches: > - PR #142 "Add dark mode toggle" -> matches "Dark mode theme option" (P1) > - v0.15.0 release includes backup/restore -> matches "Backup and restore" (P0) > > Check these off? #### Step 3: Update the file If the user already stated which items shipped (e.g., "PR #45 adds dark mode"), treat that as pre-confirmed - present the planned changes for review rather than re-asking "check these off?" For confirmed matches: 1. Apply strikethrough: `~~description~~` 2. Add attribution in the shipped-item shape from Item format: `- area | PR #N, vX.Y.Z (date)` (include both when a PR and release apply) 3. Move to the "Shipped" section (create it if missing), grouped by version or date Update the "Last updated" line in the header. --- ### Mode 3: Competitive Scan Trigger: user asks to scan competitors, provides repo URLs, or accepts the Mode 1 offer. Read `references/competitive-scan.md` for target selection, forge CLI commands, strict fit filtering, approval flow, and Competitive Intel formatting. --- ### Mode 4: Review / Prioritize Trigger: user asks to review the roadmap, prioritize, or "what should I work on next". #### Step 1: Load and summarize Read ROADMAP.md. Present a summary: - Item counts by priority tier - Items currently in progress (if tracked) - Recently shipped items - Stale items: items untouched for 60+ days are candidates for archival or re-prioritization (use per-item dates or recorded history; git blame cannot date an ignored file, and file mtime does not establish individual item age) #### Step 2: Suggest actions Based on the current state, flag any of these: - **P0 items not being worked on** - supposed to be urgent; needs explanation or demotion - **Items untouched 60+ days** - park with reason or promote; sitting isn't a priority - **Related items scattered across tiers** - group into a cohesive effort - **Shipped items still in active sections** - move to Shipped - **Missing structure** - suggest organizational improvements #### Step 3: Offer structural improvements If the roadmap lacks clear organization, suggest improvements: - Adding priority tiers if everything is a flat list - Separating product work from promotion/go-to-market - Adding a Snapshot section for project context - Adding exit criteria for major milestones - Creating an Experiments section for low-confidence ideas Present suggestions. Apply only what the user approves. #### Step 4: Apply changes With user approval, reorganize, re-prioritize, park, or remove items. Never delete silently - move to **Parked** with a reason, or confirm deletion explicitly. --- ## Reference Files - `references/trigger-integration.md` - optional auto-trigger setup for Claude Code hooks, GitHub Actions, and git hooks. Read this when the user wants push-based roadmap updates instead of (or in addition to) the built-in activity detection. - `references/competitive-scan.md` - competitor/repo scan workflow, evidence thresholds, and ROADMAP.md Competitive Intel formatting. ## Output Contract See `references/output-contract.md` for the full contract. - **Skill name:** ROADMAP - **Deliverable bucket:** `deliverables` - **Mode:** conditional. When invoked to **analyze, review, audit, or improve** an existing roadmap (e.g., "review my ROADMAP.md"), emit the full contract - monospace inline header, severity-grouped inline summary, linked Markdown deliverable, and concise monospace conclusion - and write the deliverable to `docs/local/deliverables/roadmap/-.md`. When invoked to **build or update a roadmap** (its primary mode, writing to the user's working-directory `ROADMAP.md`), respond freely without the contract; build-mode output goes to `ROADMAP.md` in the working directory, not to `docs/local/`. - **Severity scale:** `P0 | P1 | P2 | P3 | info` (see shared contract; only used in audit/review mode). ## Related Skills - **browse** - competitive scan (Mode 3) may use browse for reading competitor repos and documentation when web fetch alone isn't sufficient - **git** - update mode (Mode 2) reads git history and PR data to match shipped work - **code-review** - reviews code correctness. This skill tracks what to build; code-review evaluates the code that implements it - **update-docs** - updates project documentation AND audits ROADMAP.md for factual drift (header version, shipped highlights, items that already shipped but still listed as planned). This skill owns prioritisation, capture, and competitive intel; update-docs owns keeping the file's facts in sync with HEAD. Boundary: ideas + sequencing here, factual freshness there. ## Rules 1. **Gitignore by default.** Ensure ROADMAP.md is in .gitignore before creating or writing it. Skip only if the user explicitly asks to track it in git. 2. **Don't rewrite the file.** Edits are additive or targeted. Don't reformat, reorder, or restructure sections the user didn't ask to change. 3. **Attribute competitive intel.** Every idea from another repo gets a source tag. Never present external features as original ideas. 4. **Ask before checking off.** Present matches and let the user confirm. Don't auto-complete roadmap items based on fuzzy matches alone. 5. **One offer per session.** Ask about competitive scanning at most once. If declined, drop it. 6. **No priority inflation.** Default to P1 when priority is unclear. P0 is reserved for genuine blockers, not aspirational items. 7. **Preserve user voice.** Keep the user's phrasing when adding ideas. Clean up only when genuinely unclear. 8. **Work within existing structure.** If a ROADMAP.md exists, adapt to its format. Suggest structural changes through review mode, not silently during adds or updates. 9. **Headless mode.** In non-interactive contexts (`--bare`, Cursor Automations, Codex `exec`): skip confirmation prompts, apply only exact matches in Mode 2, add only strong-signal items in Mode 3, and don't offer competitive scans in Mode 1.