product-roadmap
Skill145 starsChanged 23 days agoMITView on GitHub
Use when doing weekly progress checks or milestone validation — tracks decision, execution, evidence, and gate states across four layers of truth.
4 other projects use a version of this.
Adopted by
Most recently taken up by
- SkillMedev/product-manager-stacktheir own version, first seen Oct 20, 2026
- iskron-ai/skillstheir own version, first seen Oct 9, 2026
- CrazyElephantX/OpenCodetheir own version, first seen Aug 10, 2026
- walternate/skillstheir own version, first seen Feb 5, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- CrazyElephantX/OpenCode★ 2same name
- iskron-ai/skills★ 2same name
- SkillMedev/product-manager-stack★ 0same name
- walternate/skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository48 other files it gives its agents.
- architect-analyzeSkill
- architect-bootSkill
- architect-clarifySkill
- architect-implementSkill
- architect-initSkill
- architect-specifySkill
- writing-skillsSkill
- change-bootSkill
- change-clarifySkill
- change-initSkill
- change-publishSkill
- change-specifySkill
- evals-analyzeSkill
- evals-clarifySkill
- evals-implementSkill
- evals-initSkill
- evals-specifySkill
- evals-validateSkill
- factory-cleanSkill
- factory-initSkill
- factory-intentSkill
- factory-learnSkill
- factory-missionSkill
- factory-orchestratorSkill
- factory-queueSkill
- factory-releaseSkill
- factory-reviewSkill
- factory-runbookSkill
- factory-setupSkill
- factory-ticketsSkill
- mission-briefSkill
- product-analyzeSkill
- product-bootSkill
- product-clarifySkill
- product-implementSkill
- product-initSkill
- product-specifySkill
- team-bootSkill
- team-constitutionSkill
- team-diagnoseSkill
- team-discoverSkill
- team-initSkill
- team-levelupSkill
- team-repairSkill
- team-setupSkill
- team-skillsSkill
- workspaceSkill
- tech-radar-bootSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 7 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
Before release to verify milestone completion
- Distinctive: line 27
After closing issues to check if milestone can be promoted
- Very specific: line 31
No PDRs exist (use /product-specify or /product-init first)
- Distinctive: line 74
Use as the authoritative execution rollup.
- Distinctive: line 79
If neither available → report issue refs as "state unknown" + one warning per tracker
- Very specific: line 96
Read the PDR's ### Evidence section (list of code paths/symbols)
- Very specific: line 97
Verify each path exists: test -f "{path}" or test -d "{path}"
- Distinctive: line 101
No Evidence section → reuse product-init's directory-detection logic
- Very specific: line 102
Check if the PDR's Feature-Area directory exists: test -d "src/{feature-area}/"
- Very specific: line 110
Read each milestone PDR's ### Gates table.
- Very specific: line 184
Regenerate
pdr.mdindex: after any updates. - Distinctive: line 188
When querying issue states, detect available tools in this order:
- Distinctive: line 211
Never report "complete" based on one layer alone
- Very specific: line 226
Only update PDR status, not PRD directly — /product-implement regenerates PRD
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
product-roadmap
What this skill does
Tracks product milestone progress across four layers of truth — because "done" is a stronger claim than "tasks complete":
| Layer | Question | Source |
| Decision | Was the decision made/approved? | PDR status (Proposed → Accepted → Completed) |
| Execution | Was the work done? | Live issue states via MCP (GitHub / GitLab / Jira / Linear) |
| Evidence | Does the code actually show it? | Code-vs-PDR verification (init concept) |
| Gates | Was the bar cleared? | Milestone PDR gate table |
A milestone is live only when all four layers are green. Anything less gets a done-means warning.
When to use
- Weekly progress check
- Before release to verify milestone completion
- Quarterly roadmap review
- After closing issues to check if milestone can be promoted
When NOT to use
- No PDRs exist (use
/product-specifyor/product-initfirst) - You want to create PDRs (use
/product-specify)
Execution Steps
Phase A: Load PDRs
sh: scripts/bash/setup-product-roadmap.sh [--json]
ps: scripts/powershell/setup-product-roadmap.ps1Read PDR files (memory first, drafts fallback; memory dual-reads
docs/adlc/memory/pdr/ then legacy .adlc/memory/pdr/ per the shared layout):
{REPO_ROOT}/docs/adlc/memory/pdr/PDR-*.md+ legacy{REPO_ROOT}/.adlc/memory/pdr/PDR-*.md(Accepted/Completed){REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md(Proposed/Discovered)
Identify milestones: PDRs with Category: Milestone. These define the roadmap structure and contain the ### Gates table, ### Features Included table, ### Done Means definition, and optional ### Tracker Milestone URL.
Phase B: Issue State via MCP
Extract issue URLs from all PDRs — look for ### Issues sections containing full URLs.
Detect tracker from URL host:
| URL host | Tracker | MCP tool pattern |
github.com | GitHub | github_* MCP tools |
gitlab.com | GitLab | gitlab_* MCP tools |
*.atlassian.net | Jira | jira_* MCP tools |
linear.app | Linear | linear_* MCP tools |
Query issue states — for each issue URL, use the matching MCP tool to get state (open/closed/in-progress):
GitHub: gh issue view NNN --json state,title,labels (CLI fallback if MCP unavailable)
GitLab: glab issue view NNN (CLI fallback)
Jira: jira issue view ISSUE-KEY (CLI fallback)
Linear: linear issue view ISSUE-ID (CLI fallback)Native milestone link — if a milestone PDR has a ### Tracker Milestone URL:
- Pull native progress directly from the tracker (closed/total + due date)
- Use as the authoritative execution rollup; skip per-issue queries for that milestone
Degradation ladder (when MCP or CLI unavailable):
- Try MCP tool for that tracker
- Fall back to CLI (
gh/glab/jira/linear) - If neither available → report issue refs as "state unknown" + one warning per tracker
Execution status per issue:
| State | Meaning |
closed / done | ✅ Work complete |
open + in-progress label/assignee | 🔄 In progress |
open + unassigned | ⏳ Not started |
Phase C: Code-vs-PDR Verification (Init Concept)
Code is ground truth; PDRs are claims. A feature marked complete where the code shows nothing is drift.
For each feature PDR in a milestone, verify code evidence:
Mode A — Explicit Evidence (preferred):
- Read the PDR's
### Evidencesection (list of code paths/symbols) - Verify each path exists:
test -f "{path}"ortest -d "{path}" - Status:
verified(all paths exist) |stale(some paths missing) |missing(no Evidence section)
Mode B — Heuristic (fallback, init-style):
- No Evidence section → reuse product-init's directory-detection logic
- Check if the PDR's
Feature-Areadirectory exists:test -d "src/{feature-area}/" - Optionally grep for title keywords in the codebase
- Lower confidence — reported as "heuristic evidence"
Hand-off rule: deep re-discovery is NOT roadmap's job. When evidence is missing/stale on a "Completed" item, the report says: "⚠️ Code evidence missing — run /product-init to re-discover". Roadmap does lightweight checks; full discovery stays in init.
Phase D: Gate Rollup
Read each milestone PDR's ### Gates table. For each gate:
| Gate type | How to check |
engineering | Check linked issue states or Evidence verification |
sign-off | Check for approval evidence (date recorded, approver named) |
time | Calculate elapsed days since cutover date vs. required period |
Gate status: green (criterion met + evidence recorded) | pending (not yet met) | unknown (no gates section — legacy PDR)
Phase E: Report
Generate the combined four-layer progress report:
## Product Roadmap Progress
### M01: Q2 User Auth — *Done means: production traffic on new auth, legacy login retired*
Tracker: github.com/org/repo/milestone/3 (native: 67% closed, due Sep 5)
| Item | Decision | Execution | Evidence | Status |
|------|----------|-----------|----------|--------|
| PDR-003: OAuth2 login | ✅ Completed | ✅ 3/3 closed (#142–#144) | ✅ src/auth/oauth/ verified | Live |
| PDR-004: SSO | ✅ Accepted | 🔄 2/4 closed (#186–#189) | ⚠️ no evidence section | In progress |
| PDR-005: Password reset | 🔄 Proposed | ⏳ 0/2 (#190, #191) | ❌ src/auth/reset/ missing | Not started |
| Gate | Type | Owner | Status |
|------|------|-------|--------|
| Security review passed | engineering | Sec team | ✅ green |
| Clinician sign-off | sign-off | Maya | ⏳ pending |
| 7-day cooling period | time | Lead | ⏳ pending (day 3/7) |
**Features**: 1/3 · **Issues**: 5/9 closed · **Gates**: 1/3 green · **Live**: No
⚠️ Done-means check: "production traffic on new auth" cannot be true while
2 items lack execution and 2 gates are pending.Done-means warnings — when a milestone claims "live" or "complete" but layers aren't green:
| Condition | Warning |
| All features Completed but issues still open | "⚠️ Features claim complete but N issues still open — execution not finished" |
| All issues closed but code evidence missing | "⚠️ Issues closed but code evidence missing — verify with /product-init" |
| All features done but gates pending | "⚠️ Features done, milestone NOT live — N gates pending: [list]" |
| Milestone marked Completed but no gates section | "⚠️ Milestone has no gates — consider adding acceptance criteria" |
Summary across milestones:
## Overall Roadmap
| Milestone | Target | Features | Issues | Gates | Live |
|-----------|--------|----------|--------|-------|------|
| M01: Q2 User Auth | Sep 5 | 1/3 | 5/9 | 1/3 | No |
| M02: Q3 Enhancements | Oct 15 | 0/2 | 0/5 | 0/2 | No |Phase F: Update Status (Optional)
Only if user explicitly requests update (e.g., "update" in arguments):
For each feature PDR:
- All linked issues closed AND evidence verified → update status to
Completed - Issues still open OR evidence missing → block update, report: "Cannot mark PDR-XXX as Completed: N issues open / evidence missing"
- Override: user explicitly says "force" → update with a warning annotation
For each milestone PDR:
- All features Completed AND all gates green → update status to
Completed - Otherwise → block update, report pending items/gates
- Override: user explicitly says "force" → update with warning
Write updated PDR files with new status, preserving all other content.
Regenerate pdr.md index after any updates.
Tracker Detection Order
When querying issue states, detect available tools in this order:
- MCP tools (preferred) — check which MCP servers are connected:
- GitHub:
github_*tools available - GitLab:
gitlab_*tools available - Jira:
jira_*tools available - Linear:
linear_*tools available
- GitHub:
- CLI fallback — if MCP for that tracker is unavailable:
- GitHub:
ghCLI - GitLab:
glabCLI - Jira:
jiraCLI - Linear:
linearCLI
- GitHub:
- No access — if neither MCP nor CLI is available for a tracker:
- Report issue URLs as "state unknown"
- Emit one warning per unresolvable tracker
- Continue with decision/evidence/gate layers
Key Rules
Four-Layer Honesty
- A milestone is live only when ALL four layers are green (decision + execution + evidence + gates)
- Never report "complete" based on one layer alone
- Done-means warnings are mandatory when layers disagree
Issue References
- Issue URLs in PDRs must be full URLs (host determines tracker)
- Native tracker milestone links are optional but preferred (pull native progress)
- Missing issue refs → execution layer reported as "no tracker linkage"
Code Verification
- Mode A (explicit Evidence) is preferred — PDRs should carry
### Evidencewith code paths - Mode B (heuristic) is a fallback — lower confidence, reported as such
- Deep re-discovery is init's job, not roadmap's — hand off with a suggestion
Status Updates
--updateblocks on pending issues/gates/evidence unless explicit override- Only update PDR status, not PRD directly —
/product-implementregenerates PRD - Preserve all other PDR fields when updating status
Backward Compatibility
- PDRs without
### Gates→ gates layer = "no gates declared" + hint to add them - PDRs without
### Issues→ execution layer = "no tracker linkage" - PDRs without
### Evidence→ evidence layer = heuristic (Mode B) - Legacy milestones still work — completion = features only, with a suggestion to adopt gates
Configuration
PDR_DRAFTS_DIR—{REPO_ROOT}/.adlc/drafts/pdrPDR_MEMORY_DIR—{REPO_ROOT}/docs/adlc/memory/pdr(legacy.adlc/memory/pdrread-compatible; counts sum both roots)PRD_FILE—{REPO_ROOT}/docs/adlc/product/PRD.md- MCP servers — GitHub, GitLab, Jira, Linear (auto-detected)
- CLI tools —
gh,glab,jira,linear(fallback)
12-Factor Alignment
- Factor III (Mission Definition): Tracks mission progress with honest done-means semantics
- Factor IX (Verification-First): Verifies claims against code evidence and live tracker state
- Factor XI (Directives as Code): Gate state is version-controlled inside PDR files
Common Rationalizations
| Rationalization | Reality |
| "The issues are all closed, so it's done." | Closed issues don't prove the code works. Evidence layer catches drift. |
| "I'll just mark the PDR as Completed manually." | Without gates green, "Completed" is a claim, not a verified state. --update blocks this. |
| "We don't need issue tracking — PDR status is enough." | Self-reported status drifts. Live tracker state is ground truth for execution. |
| "The roadmap can't reach the tracker, so let's skip it." | Degradation is built in — report "state unknown" and continue with other layers. |
Red Flags
- Marking a milestone live with pending gates — gates are the bar, not a suggestion.
- Trusting issue state without code evidence — closed issues can close prematurely; code is ground truth.
- Skipping the done-means check — "code ready" ≠ "production traffic moved". The Done Means field exists precisely to prevent this confusion.
- Running full discovery inside roadmap — deep re-discovery is init's job. Roadmap does lightweight checks and hands off.
Verification
- All PDR files loaded (memory + drafts)
- Milestone PDRs identified with their Features Included and Gates tables
- Issue URLs extracted from PDRs
- Issue states queried via MCP (or CLI fallback, or reported as unknown)
- Native tracker milestone progress pulled where links exist
- Code evidence verified (Mode A explicit, Mode B heuristic)
- Gate states rolled up per milestone
- Four-layer report generated with per-item status
- Done-means warnings emitted for mismatched layers
- Overall roadmap summary table generated
--updateblocked correctly on pending layers (if requested)pdr.mdindex regenerated after any updates- Zero files modified unless
--updateexplicitly requested
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

