/product-roadmap

name: product-roadmap
description: Use when doing weekly progress checks or milestone validation — tracks decision, execution, evidence, and gate states across four layers of truth.
disable-model-invocation: true

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-specify` or `/product-init` first)
• 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.ps1

**Read PDR files** (memory first, drafts fallback; memory dual-reads `docs/adlc/memory/pdr/` then legacy `.adlc/memory/pdr/` per the shared layout): 1. `{REPO_ROOT}/docs/adlc/memory/pdr/PDR-*.md` + legacy `{REPO_ROOT}/.adlc/memory/pdr/PDR-*.md` (Accepted/Completed) 2. `{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): 1. Try MCP tool for that tracker 2. Fall back to CLI (`gh`/`glab`/`jira`/`linear`) 3. 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 `### Evidence` section (list of code paths/symbols)
• Verify each path exists: `test -f "{path}"` or `test -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-Area` directory 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 gr