Roadmap

---
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 <repo-url> | 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`'s stated version numbers or release-highlight prose - use **update-docs**. This skill owns item status itself: Mode 2 moves shipped `[planned]` / `[exploring]` items to Shipped. update-docs owns the header version and highlight text; roadmap owns which items count as shipped.
- 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} ({strong signal | 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

---

## Prioritization Practices

- Limit active P0/P1 items so prioritization remains meaningful.
- Group duplicate ideas and link evidence instead of copying long notes repeatedly.
- 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)

Before reporting roadmap state, inspect the available repository root, ROADMAP.md, ignore rules,
README, and primary package/project metadata. Distinguish observed, missing, and unavailable state;
never infer that a roadmap is absent or ignored when the repository cannot be inspected. Name any
project context that was unavailable.

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
command -v gh; command -v glab   # forge CLI: gh (GitHub), glab (GitLab), or git-only
# 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.

Copy this checklist and track progress:

- [ ] Step 1: Recent activity gathered (or named PRs fetched)
- [ ] Step 2: Matches presented and confirmed
- [ ] Step 3: Confirmed items moved to Shipped with attribution; header date updated
- [ ] Step 4: File re-read; if a confirmed item is still in an active tier or lacks attribution, fix it and return to Step 4

#### 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 `Updated:` date in the header.

#### Step 4: Verify the edit

Re-read ROADMAP.md. Each confirmed item appears once, under Shipped, with its PR or release
attribution, and unconfirmed items are untouched. Fix any miss and repeat this step.

---

### 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 3 requires a bounded, reaction-sorted forge query, or a documented equivalent when that forge
cannot sort by reactions. Apply the reference's repository-size-calibrated strong/weak/noise
thresholds, attribute every candidate, and present candidates for approval before writing them.

---

### 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"), apply the reporting size and evidence rules in `references/output-contract.md` and write the deliverable to `docs/local/deliverables/roadmap/<YYYY-MM-DD>-<slug>.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

- Use the host's browsing tools during competitive scans (Mode 3) to read 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 in
  the header version and release-highlight prose. This skill owns prioritisation, capture,
  competitive intel, and item status (Mode 2 moves shipped items out of the active tiers);
  update-docs owns the stated version and highlight text staying in sync with HEAD.

## 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. **Attribute competitive intel.** Every idea from another repo gets a source tag. Never
   present external features as original ideas.
3. **Ask before checking off.** Present matches and let the user confirm. Don't auto-complete
   roadmap items based on fuzzy matches alone.
4. **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.