agile-product-report

name	agile:product:report
description	Generate or update a comprehensive progress report for a Product Requirements Document (PRD). Builds the full reference graph from PRD → Initiatives → Epics → Features → Tasks (and the optional direct PRD → Epic shortcut path), cross-validates linkages in both directions, detects orphans and drift, aggregates four-tier metrics (initiative realization, epic realization, implementation, overall), and writes a regenerable progress.md beside the PRD. Read-only over initiative, epic, feature, and task artifacts. Use when the user asks about product progress, product status, "how far along is the product", PRD progress, PRD status, PRD report, product roadmap progress, or wants a cross-initiative product dashboard. Triggers on "product report", "product progress", "PRD progress", "PRD status", "PRD report", "PRD dashboard", "regenerate product report", "product roadmap status", "how far along is the PRD", "product realization", "product implementation", "track all initiatives epics features for PRD", "PRD reference graph".
user-invocable	true
allowed-tools	Read, Write, Bash, Glob, Grep, AskUserQuestion

Product Report

Produce a single-file dashboard of a PRD's full implementation progress. Walks every initiative that derives from the PRD, every epic under those initiatives (and any epics that link directly to the PRD), every feature inside those epics, and every task inside those features — then summarises realization, implementation, orphans, and roadmap timing.

This skill is read-only over every artifact except the report itself. It never edits initiative design.md, epic design.md / epic.md, feature spec.md, or any tasks.md. The only file it writes is agile/product/<slug>/progress.md (plus an optional debug agile/product/<slug>/.progress-graph.json), both fully regenerable.

Invocation

/agile:product:report <slug-or-number>

# Examples
/agile:product:report 001
/agile:product:report 001-sso-modernization
/agile:product:report                       # interactive: pick from agile/product/
/agile:product:report --no-write 001        # show on stdout, do not write
/agile:product:report --graph-only 001      # emit only the JSON graph (debug)

When to use

• You want one rolled-up answer to "is this product actually shipping?" without opening eight initiatives and seventy-five epics.
• You want a regenerable file (committable, reviewable, diffable) that captures the PRD → Initiative → Epic → Feature → Task graph at a moment in time.
• You want to surface drift: initiatives that backlink to the PRD but aren't in its candidate table, candidate epics in the PRD that nobody has built, epics whose initiative does not itself link to the PRD.

When NOT to use

• You want to modify epic / initiative artifacts — use agile-epic-progress or agile-initiative-progress instead. This skill never writes outside agile/product/.
• You want to push work items to Azure DevOps — this skill does not touch DevOps. It only displays DevOps IDs that already exist in artifact metadata.
• You only need a single epic's progress — use agile-epic-progress.
• You only need a single initiative's progress — use agile-initiative-progress.
• The PRD has not yet been approved (status DRAFT) — refine it first via /agile:product:refine.

Reference graph the skill builds

PRD <slug>                                    [agile/product/<slug>/prd.md]
├── Initiative A   (status, realization%, implementation%)
│   ├── Epic A1    (status, tasks done/total, %)
│   │   ├── Feature A1-01  (status, tasks)
│   │   ├── Feature A1-02
│   │   └── ...
│   ├── Epic A2
│   └── ⚠ Orphan epic   (backlinks initiative but isn't in its candidate table)
├── Initiative B
│   └── ...
├── ⚠ Direct epic    (epic with `product: <slug>` frontmatter, no intermediate initiative)
└── ⚠ Missing initiative   (PRD lists it but no design.md backlinks the PRD)

The graph is built from both directions so drift surfaces automatically:

1. Forward — what the PRD declares it intends:
   • PRD §10 ## 10. Epic Candidates table (epic IDs / names) — direct path, optional.
   • PRD frontmatter related_epics: list — direct path, optional.
   • PRD body or frontmatter initiatives: if introduced — initiative path, optional/future.
2. Backward — what other artifacts claim about the PRD:
   • Initiative design.md YAML frontmatter product: <slug> (canonical, future).
   • Initiative design.md prose header **Derived from**: PRD <NNN[-slug]> (legacy, current).
   • Epic design.md YAML frontmatter product: <slug> (canonical, future direct link).
   • Epic epic.md / design.md prose **Product**: <NNN-slug> (legacy direct link).

The skill accepts both canonical and prose linkage at every layer, mirroring the dual-mode pattern used by agile-initiative-progress for epic backlinks. New PRDs / initiatives / epics SHOULD adopt canonical YAML frontmatter; legacy artifacts continue to work via prose.

Phases

Phase 0 — Resolve the PRD

1. Parse $ARGUMENTS. Strip leading @ if the user pasted a path.
2. Resolve the PRD directory under agile/product/:
   • Numeric input (e.g. 001, 1) → match agile/product/<NNN>-* (zero-padded).
   • Slug input (e.g. 001-sso-modernization) → exact directory match.
   • Path input (agile/product/...) → use as-is.
   • No argument → use AskUserQuestion to list every directory under agile/product/ with its current status, asking the user to pick one. If agile/product/ does not exist or is empty, report that no PRDs exist and stop.
3. Verify agile/product/<slug>/prd.md exists. If not, fail loudly — do not write a stub.
4. Read the PRD's status from frontmatter status: and from the **Status**: body line. Allow APPROVED, REFINED, IMPLEMENTING, COMPLETED. Warn (do not block) on DRAFT or REVIEW.

Phase 1 — Build the reference graph

Run the scan + compute script:

python3 .claude/skills/agile-product-report/scripts/compute-product-progress.py \
  <slug> [--repo-root <path>] [--write] [--no-write] [--out <path>] [--graph-only]

Default behaviour: write the rendered markdown to stdout AND write agile/product/<slug>/progress.md (plus the debug graph JSON beside it). --no-write skips both files; --graph-only skips the markdown and writes only the JSON.

Internally the script:

1. Reads prd.md, parses YAML frontmatter, body status, and §10 Epic Candidates table.
2. Globs agile/initiatives/*/design.md and identifies every initiative whose frontmatter product: or prose **Derived from**: PRD <NNN[-slug]> matches this PRD.
3. For each linked initiative, parses its ## Epic Candidates table.
4. Globs agile/epics/*/{design.md,epic.md} and identifies epics that:
   • Match an initiative's initiative: frontmatter (most epics today), OR
   • Match the PRD directly via epic frontmatter product: / prose **Product**:.
5. For every realized epic, scans its feature subdirectories (<epic>/<NNN>-<NN>-*/) and counts task markers in each tasks.md using the standard 6-state convention.
6. Cross-checks forward (PRD-declared candidates) against backward (artifact backlinks) and produces orphan / missing lists at every layer.
7. Aggregates four headline percentages.

Phase 2 — Present and write

1. Display the rendered progress.md to the user (the script prints to stdout).
2. Use AskUserQuestion with these options:
   • Keep written progress.md (recommended) — file already saved during Phase 1.
   • Discard — delete the file — remove progress.md and .progress-graph.json.
   • Show graph JSON — print the debug JSON for inspection, then re-ask.
3. If kept, display the path. Do not auto-commit — the user decides.

Phase 3 — Next steps

After the report is rendered, suggest follow-ups appropriate to the report's content (do not auto-invoke any of them):

• Drilldown for a specific initiative: /agile:initiative:progress <slug>.
• Drilldown for a specific epic: /agile:epic:progress <id>.
• Brainstorm unrealized initiative or epic candidates: /agile:initiative:brainstorm / /agile:epic:brainstorm.
• Reconcile orphans by editing the PRD (add candidate row) or the orphan artifact's frontmatter (remove backlink), depending on intent.

Progress computation

6-state task markers

Same convention as the rest of the agile skills:

Marker	Meaning	Counted as
[ ]	pending	incomplete
[W]	working	incomplete
[X]	done	complete
[B]	blocked	incomplete
[S]	skipped	excluded
[-]	skipped (alt)	excluded

Per-epic completion = done / (total - skipped) × 100, with the well-known ## Task Status Reference table inside every tasks.md filtered out so its example markers do not pollute counts.

Four-tier aggregation

Metric	Formula
Initiative Realization	realized_initiatives / (linked_active_initiatives + missing_initiatives) × 100. "Realized" means the linked initiative directory exists and has design.md. "Missing" means PRD lists it as a candidate but no backlinking design.md was found.
Epic Realization	realized_epics_total / candidate_epics_total × 100 summed across every linked initiative plus any direct PRD epic candidates. Retired candidates excluded.
Implementation	Mean of per-epic completion percentages across every realized epic the graph touches. Epics with no tasks count as 0% (honesty bias — a green status without tasks should not inflate the headline).
Overall	Initiative Realization × Epic Realization × Implementation / 10000. The honest single-number that is hard to game: a PRD only reaches 100% when every initiative is realized, every epic candidate is realized, and every task is done.

If the PRD has no initiative candidates and no direct epic candidates, the report renders with all four metrics at 0% and a clear "no work derived yet" notice. This is informational, not an error.

Orphan + drift detection

Class	Definition	Surfaced as
Orphan initiative	design.md backlinks this PRD (frontmatter or prose) but no candidate row in the PRD lists it	"⚠ Orphan initiatives" table
Missing initiative	PRD lists candidate but no initiative design.md backlinks the PRD	"⚠ Missing initiatives" table
Orphan epic (under initiative)	epic.md initiative: matches but no candidate row in initiative — delegated to per-initiative report; surfaced here as a count
Direct orphan epic	epic backlinks PRD directly (not via an initiative) but no candidate row in PRD §10	"⚠ Direct orphan epics" table
Missing epic (direct)	PRD §10 names an epic that has not been realized	"⚠ Unrealized direct epics" table

Output sections

The rendered progress.md follows templates/progress-template.md and contains, in order:

1. Header + regenerate command + PRD link
2. Summary — 4-tier metrics, totals, retired / orphan / missing counts
3. Reference Graph — ASCII tree of PRD → Initiatives → Epics → Features (collapsed past feature level) with per-node status / completion
4. Initiative Summary Table — per-initiative realization, implementation, overall
5. Epic Catalog (flat) — every epic touched, with status, feature count, task counts, DevOps ID
6. Orphan & Drift Report — the five orphan / missing classes above
7. DevOps Linkage — work-item IDs at every layer (PRD, initiatives, epics)
8. Roadmap Timeline — epics grouped by Sprint field from epic.md (best-effort parse)
9. Closeout Readiness — checklist (frontmatter status: chain, full realization, full implementation, no orphans)
10. Footer — generation timestamp, commit SHA, regenerate command, "do not edit by hand"

Scripts

Script	Purpose
scripts/compute-product-progress.py	Single entry point. Performs scan, builds graph, renders markdown, writes graph JSON.

The skill is intentionally a single-script implementation. Earlier drafts split scanning and rendering into multiple files; consolidating gives one place to read for behaviour and one place to test. The script is self-contained — it does NOT depend on the (currently missing) agile-epic-brainstorm/scripts/scan-initiative-epics.py referenced by sister skills.

Templates

Template	Purpose
templates/progress-template.md	Markdown skeleton with {PLACEHOLDERS} filled by the script.

References

Reference	Purpose
references/reporting-methodology.md	Why the four-tier formula is the honest aggregate, how the graph is walked, how orphans are classified.

Related skills

• agile-product-brainstorm creates the PRD this skill reports on.
• agile-product-refine stress-tests an APPROVED PRD before initiatives derive from it.
• agile-initiative-progress is the per-initiative version of this skill.
• agile-epic-progress is the per-epic version (also pushes status fixes back to artifacts; this product-level skill never does that).

Safety

• NEVER edit any file outside agile/product/<slug>/.
• NEVER push to Azure DevOps. Display existing IDs only.
• NEVER auto-invoke a downstream skill (drilldown, brainstorm, etc.) — only suggest commands.
• If the PRD cannot be resolved or prd.md is missing, fail loudly with the error; do not create a stub directory.
• Numbers in this report MUST match the per-initiative numbers shown by /agile:initiative:progress for the same initiative. If they diverge, treat that as a bug in this skill, not a reason to silently round.