---

name: prd-review description: Three-mode PRD tool — score for agentic readiness, challenge gaps against repo and story flows, or convert a draft into a well-formed tactical PRD. Use when the user wants a scored assessment (--score), wants user stories and repo reality confronted (--challenge), or wants a draft rewritten into an execution-ready spec (--convert). argument-hint: [--score | --challenge | --convert] <prd-path-or-url> [repo-path] disable-model-invocation: true allowed-tools: Read WebFetch Write Bash(textutil -convert txt -stdout *) Glob Grep

PRD Review

Use this skill when the user wants a real PRD assessment, not a surface-level checklist scan. Your job is to review the PRD the way a senior PM + engineering lead would — catching gaps, ambiguities, risks, and missing context before a single line of code is written.

The goal of this review is agentic execution readiness: after this review, the score tells you whether an AI agent or engineer can generate a correct RFC, data models, and code from this PRD — without a clarification meeting. The score is the go/no-go gate before the engineering phase begins.

This skill has three modes. The default is Score. All modes read a PRD; Challenge and Convert also accept an optional repo path for grounding.

---

Mode Detection

Parse the first token after the skill name:

| First token | Mode | Output | |---|---|---| | absent or --score | Mode 1 — Score | Scored assessment report ({prd-name}-report.md) | | --challenge | Mode 2 — Challenge | Gap analysis: stories vs. repo and flow ({prd-name}-challenge.md) | | --convert | Mode 3 — Convert | Rewritten tactical PRD ({prd-name}-tactical.md) |

Argument parsing after the flag:

• First remaining token = PRD (path, URL, or treat as pasted if multi-word)
• Second remaining token (optional) = repo root path — used in Mode 2 and 3 for repo scanning
• If no PRD is provided in any mode: ask the user to supply it as a path, URL, or pasted content, and confirm which mode they want

---

Input handling

The skill accepts five input forms:

1. Text file — user passes a path to a .md, .txt, .rst, or similar plain-text file; read with the Read tool.
2. PDF — user passes a .pdf path; read with the Read tool. For large PDFs, read in page ranges (e.g. pages: "1-10").
3. Word document — user passes a .docx or .doc path; extract text with:

   textutil -convert txt -stdout <path>
   

4. URL — user passes a Confluence, Notion, or Google Docs URL:
   • Public URL: fetch with WebFetch.
   • Confluence via MCP: if a Confluence MCP is installed and available, use its page-fetch tool to retrieve authenticated content. Add the MCP tool name to allowed-tools in the SKILL.md frontmatter once the MCP is set up.
   • If access fails by any method, ask the user to export or paste the content.
5. Pasted content — user pastes PRD text directly; analyze what was provided.

If no argument is passed, ask the user to provide the PRD as a file path, URL, or pasted content.

Default output path

• Derive {prd-name} from the PRD:
  • File path argument: use the filename stem (e.g. my-feature.md → my-feature)
  • URL: use the last path segment or page title slug
  • Pasted content: use the first heading or first 5 words, lowercased, spaces replaced with -
• Write the report to {prd-name}-report.md:
  • If the user passed a path argument: same directory as the PRD file
  • Otherwise: current working directory
• If a report file already exists at that path, overwrite it directly — do NOT read the existing file first.
• Never write outside the current working directory.
• Reject absolute paths and parent traversal such as ../.

Assessment rules

• This is a judgment-based review. Do not tick boxes mechanically.
• Cite specific sections, sentences, or fields from the PRD. Do not make generic claims.
• Focus on whether a cross-functional team can start building without a follow-up meeting.
• For user stories: run the full UST protocol (element check + challenge) — not just acceptance criteria.
• If a section is absent, record that absence explicitly. Do not skip silently or assume it exists elsewhere.
• Use 0.5 score increments for category scores and the overall score.
• Calibrate to PRD type: strategic, tactical, experiment, bug-fix-spec, or platform. A strategic multi-team PRD needs stronger scoping and alignment than a tactical one-team experiment.
• If the PRD is clearly too thin to assess reliably, say so and explain the limiting factors.
• For approval requirements (tech lead sign-off, engineering review, legal, security): flag that the requirement must exist in the PRD, but do not check or verify whether approval has already been granted. Record it as a gap only if the requirement itself is absent from the PRD.

Non-Negotiable SOP

1. In parallel: Read rubric.md, report-template.md, and the full PRD content in a single batch of parallel reads. Do not read them sequentially.
2. Identify the PRD type (strategic, tactical, experiment, bug-fix-spec, platform) from the PRD content. This gates calibration for all 10 categories — determine it before scoring anything.
3. Single-pass scoring: Score all 10 rubric categories in one read-through of the PRD. Do not re-scan the PRD per category. Take inline notes as you read, then assign all scores at once. For each critical category (PRB, SCO, REQ, OBJ, UST), note any score cap trigger immediately as you score it — do not defer cap computation to a separate step.
4. For UST: assess every story in a single pass using the unified story checklist below — check elements, probe gaps, write suggestions simultaneously. Apply story depth rules (see below).
5. Finalize the overall score applying the strictest triggered cap.
6. Write the report and compose the chat summary in one step: open the report with the compact summary block (score, verdict, gaps, actions, story verdict, report path), then continue with the full report body. Do not make a separate pass to compose the summary — it is the report's opening section.
7. Save the report to {prd-name}-report.md.

User Story Assessment (UST) — Unified Single-Pass Protocol

This is the most critical differentiator of this skill. For each user story, assess all elements and probe for gaps in one pass.

Story checklist (assess all in one read-through)

Identity & format

• Story ID present? Standard "As a [role], I want [action], so that [outcome]" format?
• Role specific enough? Can multiple roles trigger this, and do they behave differently?

Before / After

• Current state described (what exists today, or what the workaround is)?
• Delta described as a specific change — not just the end state?

Fields (for every UI and data field touched)

• Name (UI label + data model name), Type, Purpose, Validation (required/optional, rules, format), Default, Dependency?

Business logic

• Explicit if/then rules (not implied)? Permission model (who can view/create/edit/delete/approve)? Calculations or derived fields? Side effects (events, notifications, audit logs, downstream sync)? State machine (valid transitions)?

Edge cases

• Null/empty behavior? Concurrent edits? Role-permission edge cases? Backward compatibility? Multi-tenant isolation?

Acceptance criteria

• Given/When/Then format? Covers at least one failure path? Specific enough for QA without asking the PM?

Gap probes (flag any the PRD cannot answer)

• What does the user see on failure? Is the action reversible? What happens at 0 / 1 / 1000 items? What must already exist for this story to work? Does this story conflict with or break adjacent stories?

Scoring a story and depth rules

Use the rubric labels:

• RFC-Ready: all 7 elements present AND challenge protocol finds no critical gaps. Agent can generate RFC from this story alone.
• Partial: elements 1–4 present but logic, edge cases, or challenge answers are missing. Agent would guess.
• Thin: one-liner or lacks fields and logic. Agent cannot use this story reliably.

Story depth rules — apply these to control output length:

• RFC-Ready story: write one short paragraph summarising why it passes + any minor notes. Do NOT fill out the full 7-section template. Index entry only.
• Partial story: fill the full 7-section template. For sections that are present, summarise briefly. For missing sections, write the gap explicitly and provide a concrete rewrite suggestion.
• Thin story: fill the full 7-section template with NOT SPECIFIED for every absent section. Provide a complete rewrite suggestion for the story and a list of open questions.

For each Partial or Thin story, include:

• A gap list: exactly what is missing
• A rewrite suggestion: a concrete improved version of the weakest part
• Open questions: specific questions to resolve with the PM before this story can proceed

Report the readiness rating per story AND as an aggregate for the UST category score.

Score discipline

• Category scores follow the rubric anchors, not general impression.
• 9.0+ requires at least 2 strong, non-conflicting evidence points per category.
• 10.0 is extremely rare.
• If critical categories (PRB, SCO, REQ, OBJ, UST) are materially weak, do not let polish elsewhere inflate the overall score.
• Always apply score caps from rubric.md.

Report requirements

• Make the full report concrete and evidence-backed.
• Quote or reference specific PRD sections whenever possible.
• Include: strengths, gaps, per-story UST assessment (element check + challenge results), improvement recommendations, story quality verdict.
• For each gap, write a concrete improvement suggestion — not "add more detail to story X" but the actual missing content or the specific question the PM needs to answer.
• Make recommendations sequenced and actionable, not generic.
• End the report with an Open Questions section: a numbered list of specific questions that must be answered by the PM or stakeholders before engineering can begin.
• The report is the guardrail artifact: the PM takes it back to improve the PRD, and the score is the gate that must be cleared before RFC and code generation begins. It should be uncomfortable to read if the PRD is not ready.

---

Mode 2 — Challenge

Goal: Confront the PRD with ground truth — find gaps between what the PRD claims and what the codebase, data model, or story flow actually provides. This mode produces no score; it produces a structured gap table.

Use when:

• The PRD covers an existing product or repo (not greenfield).
• You want to verify PRD assumptions against real API routes, schema, or service boundaries.
• You want to catch story flow gaps — missing preconditions, broken transitions, implicit dependencies.

Mode 2 — Input

• Required: PRD (path, URL, or paste)
• Optional: [repo-path] — root of the repo to scan. If omitted, use the current working directory if it looks like a code repo (has .git, package.json, go.mod, requirements.txt, etc.). If no repo context is detectable, run story gap analysis only.

Mode 2 — SOP

1. In parallel: Read the PRD AND (if repo available) run these scans:

   • Glob for data model files: **/*.model.{ts,js}, **/models/**/*.{ts,py,rb,go,java}, **/*.schema.{ts,prisma}, **/migrations/**
   • Glob for route/API files: **/routes/**, **/controllers/**, **/handlers/**, **/*.routes.{ts,js}, **/api/**
   • Glob for service layer: **/services/**, **/usecases/**, **/domain/**
   • Grep for 3–5 key entity names extracted from PRD story titles, searching across all code files

2. Extract PRD claims — for each user story, list:

   • Entities it assumes exist (tables, models, API endpoints)
   • Permissions it assumes are enforced
   • State transitions it assumes the system supports
   • Side effects it assumes happen (events, notifications, audit logs, downstream syncs)

3. Compare each claim against repo reality:

   • Found and matches → note as confirmed, skip in report.
   • Found but differs → flag: "PRD says status: active|inactive but model has status: enabled|disabled|pending."
   • Not found → flag as gap: assumed entity/endpoint/behavior must be built from scratch or is simply missing.
   • Conflict between stories → flag: two stories contradict each other or share an implicit dependency that isn't modeled.

4. Story flow gap analysis (always run, even without repo):

   • Map all user stories into a sequential flow.
   • Identify: missing precondition stories, stories that end without a defined next state, flows that branch but have no corresponding branch story, stories that assume a prior story's output without referencing it.

5. Write the Challenge Report to {prd-name}-challenge.md using the Challenge Report Template in report-template.md.

6. Summarise findings in chat (not in the file): total gaps found, count by type, top 3 actions.

Mode 2 — Output

Use the Challenge Report Template section of report-template.md. The report contains:

• Gap Summary Table: PRD Claim | Repo Reality | Gap Type | Impact
• Story Flow Map: numbered story sequence with gaps and conflicts highlighted
• Story-to-Story Conflicts: where stories contradict or implicitly depend on each other
• Technical Conflicts: entities, fields, or endpoints the PRD assumes but the repo doesn't match
• Recommended Actions: ordered by impact, one action per gap

The Challenge report does not score the PRD. It confronts and documents gaps only.

---

Mode 3 — Convert

Goal: Take a PRD in any format — strategic doc, narrative brief, slide-deck prose, half-written draft — and rewrite it as a well-formed tactical PRD that is agentic-execution ready: structured stories, explicit fields, business logic, and acceptance criteria.

Use when:

• A PM has a rough draft or feature brief that needs to become a buildable spec.
• You want to add repo context to ground the PRD in what already exists.
• You want to move a PRD from "intent" to "implementation-ready" before running a Score review.

Mode 3 — Input

• Required: source PRD (path, URL, or paste)
• Optional: [repo-path] — if provided, scan the repo to ground entity names, field names, and API patterns in the existing codebase instead of inventing them.

Mode 3 — SOP

1. In parallel: Read the source PRD AND (if repo-path provided):

   • Glob for data model files → extract existing entity and field names
   • Glob for route files → extract existing API path patterns and HTTP methods
   • Grep for key nouns from the source PRD → find relevant existing code to anchor story details

2. Classify the source PRD as strategic | experiment | narrative | brief | slide-notes | other. This determines how much structure must be invented vs. extracted.

3. Extract all intent signals from the source PRD:

   • Problem being solved
   • Who the users are (roles, personas)
   • What they should be able to do (even if described as prose, not stories)
   • Any goals, metrics, or success criteria mentioned
   • Any constraints, non-goals, or out-of-scope items — explicit or implied

4. Write user stories for every distinct action implied by the source PRD:

   • Format: "As a [role], I want [action], so that [outcome]."
   • For each story: fill Before/After delta, Fields table, Business Logic (if/then rules, permissions, side effects, state transitions), Edge Cases, Acceptance Criteria (Given/When/Then, happy + failure path).
   • Where information is genuinely missing: use [NEEDS PM INPUT: <specific question>] — do NOT invent business rules or validation constraints. Mark every invented assumption explicitly.
   • Where repo context is available: use real field names, endpoint path patterns, and entity names from the codebase. Cite the file or model name.

5. Write the tactical PRD to {prd-name}-tactical.md following this structure:

   • Problem Statement — extracted from source; flag gaps with [NEEDS PM INPUT]
   • Objectives & Metrics — extracted targets and KPIs, or explicitly flagged as missing
   • Scope & Boundaries — in-scope list, out-of-scope list, MVP boundary
   • Requirements — functional + non-functional, derived from stories
   • User Stories — each story in full structured format (as written in step 4)
   • UX Notes — any design signals from source PRD, or flagged as missing
   • Open Questions — all [NEEDS PM INPUT] items consolidated, numbered, assigned to PM or Eng

6. Write a conversion summary in chat (not in the file):

   • How many stories were extracted
   • How many fields were grounded in the repo vs. flagged as invented
   • How many [NEEDS PM INPUT] items remain
   • Honest verdict: is the result likely to pass a --score review, or does the PM need to answer the open questions first?