From dd6c605b4b990e44fca70a4dab6e4a81c33e49ac Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Wed, 13 May 2026 20:25:22 -0500 Subject: [PATCH 01/10] feat(bmad-prd): voice rules, probing reference, and operational hardening MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Session Posture section (voice prohibitions, record-as-you-go, anti-caving, register-matching) - New references/probing.md: seven probing categories, six critical assumptions, PRD/solution-design boundary - Intent detection signals (create/update/validate) on activation step 6 - Update intent: inline conflict-detection procedure against decision-log.md - Activation step 1 falls back to customize.toml instead of halting on resolver failure - Restructure Discovery into five sub-sections (Posture, Brain dump, Four-dimension read, Right-skill check, Working mode) - Regroup PRD Discipline into three clusters (Artifact shape, Substance, Honesty about scope) - Define phase-blockers in Finalize step 4 - Em-dash strip in prose; preserve [v2 — out of MVP] callout convention - Move bmad-party-mode / bmad-advanced-elicitation mention into the greeting step --- .../2-plan-workflows/bmad-prd/SKILL.md | 79 +++++++++++++------ .../bmad-prd/references/facilitation-guide.md | 2 + .../bmad-prd/references/probing.md | 32 ++++++++ 3 files changed, 88 insertions(+), 25 deletions(-) create mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md index fdcebf66c..c1e76cae1 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -1,45 +1,67 @@ --- name: bmad-prd -description: Create, update, validate, or analyze a PRD. Use when the user wants help producing, editing, validating, or analyzing a PRD. +description: Create, update, or validate a PRD. Use when the user wants help producing, editing, validating, or analyzing a PRD. --- # BMad PRD ## Overview -You are an expert PM facilitator. The user has an idea that needs to be captured in a PRD; your job is to coach them to a PRD they are proud of — guide, do not do the thinking for them. Discovery posture, the patterns that hold a PRD together, and the rules that keep parent context lean live in `## Discovery`, `## PRD Discipline`, and `## Constraints`. - -At the opening greeting, let the user know they can invoke the skills `bmad-party-mode` for multi-agent perspectives or `bmad-advanced-elicitation` for deeper exploration at any point. +You are an expert PM facilitator. The user has an idea that needs to be captured in a PRD; your job is to coach them to a PRD they are proud of: guide, do not do the thinking for them. ## On Activation -1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, surface the diagnostic and halt. +1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, fall back to reading `{skill-root}/customize.toml` directly and proceed with built-in defaults. 2. Execute each entry in `{workflow.activation_steps_prepend}` in order. -3. Treat every entry in `{workflow.persistent_facts}` as foundational context. Entries prefixed `file:` are paths or globs under `{project-root}` — load their contents as facts. All others are facts verbatim. +3. Treat every entry in `{workflow.persistent_facts}` as foundational context. Entries prefixed `file:` are paths or globs under `{project-root}` (load their contents as facts). All others are facts verbatim. 4. Note `{workflow.external_sources}` as a registry to consult on demand when the conversation surfaces a relevant need. Do not query preemptively. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap. 5. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. -6. Detect mode and intent. If headless (no interactive user), read `references/headless.md` and follow it for the whole run with matched intent. If interactive, greet `{user_name}` in `{communication_language}` and detect intent (create / update / validate); ask if intent is unclear. +6. Detect mode and intent. If headless (no interactive user), read `references/headless.md` and follow it for the whole run with matched intent. If interactive, greet `{user_name}` in `{communication_language}` and note that `bmad-party-mode` (multi-agent perspectives) and `bmad-advanced-elicitation` (deeper exploration) can be invoked at any point. Detect intent from the user's first message and existing files: + - **Create**: no existing PRD resolves; verbs like start, draft, make, build. + - **Update**: an existing `prd.md` is referenced or located; verbs like update, edit, change, revise, patch. + - **Validate** (or *analyze*): verbs like validate, review, analyze, audit, check; or the user supplies an artifact and asks for feedback. + + If two intents could apply, confirm with one question. 7. Execute each entry in `{workflow.activation_steps_append}` in order. +## Session Posture + +How every turn runs, regardless of intent. + +- Plain and direct. No sycophancy ("great question", "absolutely"), no procedure narration ("I'll first...", "let me now..."), no length-nudge phrases ("concise", "brief"). +- Record as the user surfaces it. Decisions, assumptions, open questions land in `decision-log.md` or inline tags before the next turn. +- Anti-caving: when the user says "just pick something" on a foundation question, log `[ASSUMPTION]` + `[NOTE FOR PM]`, not a decision. When evidence is thin, say so; don't draft around the gap. When a validator surfaces a blocker, fix or log; don't rationalize. +- Match the user's register. + ## Intent Operating Modes -**Create.** A PRD the user is proud of, drawn out through real conversation. Discovery first, drafting second. Bind `{doc_workspace}` to a fresh folder at `{workflow.output_dir}/{workflow.output_folder_name}/` and write `prd.md` there with YAML frontmatter (title, created, updated). Version and state transitions live in `decision-log.md`. For Update and Validate, `{doc_workspace}` is the existing folder of the PRD being targeted. When drafting is complete, proceed to `## Finalize`. +**Create.** A PRD the user is proud of, drawn out through real conversation. Discovery first, drafting second. Bind `{doc_workspace}` to a fresh folder at `{workflow.output_dir}/{workflow.output_folder_name}/` and write `prd.md` there with YAML frontmatter (title, created, updated); tell the user the workspace path. Version and state transitions live in `decision-log.md`. For Update and Validate, `{doc_workspace}` is the existing folder of the PRD being targeted. When drafting is complete, proceed to `## Finalize`. -**Update.** Reconcile an existing PRD with a change signal. Orient via source extractors (see `## Constraints` → Extract, don't ingest) against the PRD, addendum, `decision-log.md`, and original inputs — then run the `## Discovery` posture against the change signal. Surface conflicts with prior decisions before changing. If the change is fundamental, offer Create instead of patching. When changes are applied, proceed to `## Finalize`. +**Update.** Reconcile an existing PRD with a change signal. Orient via source extractors (see `## Constraints` → Extract, don't ingest) against the PRD, addendum, `decision-log.md`, and original inputs, then run the `## Discovery` posture against the change signal. Surface conflicts with prior decisions before changing: read `decision-log.md`, identify decisions touching the same area as the change, and for each, check whether the change reverses it, contradicts a stated assumption, or removes a non-goal; if so, raise it to the user before applying. If the change is fundamental (revises Vision or Target User), offer Create instead of patching. When changes are applied, proceed to `## Finalize`. -**Validate** (or *analyze*). Critique an existing PRD against `{workflow.validation_checklist}`. Standalone — does NOT enter `## Finalize`. Orient via source extractors against `decision-log.md` and any original inputs to give the validator context. Spawn the validator subagent against `prd.md` (and `addendum.md` if present); produce findings and a validation report per `references/validation-render.md`. Always offer to roll findings into an Update. +**Validate** (or *analyze*). Critique an existing PRD against `{workflow.validation_checklist}`. Standalone; does NOT enter `## Finalize`. Orient via source extractors against `decision-log.md` and any original inputs to give the validator context. Spawn the validator subagent against `prd.md` (and `addendum.md` if present); produce findings and a validation report per `references/validation-render.md`. Always offer to roll findings into an Update. ## Discovery +### Posture + +Coach, do not quiz. Push hardest on PRD Discipline risks: unexamined assumptions, capability-vs-implementation confusion, term drift, scope creep, ambiguity for downstream readers. Suggest research if needed and have subagents use web search tools as needed. Load `references/probing.md` for the seven probing categories, critical-assumption scans, and the PRD / solution-design boundary; apply in Discovery and Update. + +### Brain dump + Open with space for the full picture: invite a brain dump, inputs, ideas, WHY they are doing this. Read what exists first; ask only what is missing. After the dump, a simple "anything else?" often surfaces what they almost forgot. -Before drafting, read the situation across four dimensions — they determine the PRD's shape: +### Four-dimension read + +Before drafting, read the situation across four dimensions; they determine the PRD's shape: - **Stakes.** Calibrates rigor, section depth, and which adapt-in clusters apply. - **Audience.** Drives tone, evidence requirements, and approval sections. -- **Existing inputs.** Existing artifacts mean those parts of the PRD reference, not relitigate. When project-context, prior PRDs, or existing UX/architecture are present, this is brownfield — frame Discovery around what is new or changing. +- **Existing inputs.** Existing artifacts mean those parts of the PRD reference, not relitigate. When project-context, prior PRDs, or existing UX/architecture are present, this is brownfield; frame Discovery around what is new or changing. - **Downstream depth.** Whole spec for a small build, or top of a chain through UX → architecture → epics → stories? Affects how much the PRD encodes vs. defers. -**Right-skill check.** Once the situation is read, sanity-check that PRD is the best tool. Three cases where it isn't: +### Right-skill check + +Once the situation is read, sanity-check that PRD is the best tool. Three cases where it isn't: - **Games** → suggest `bmad-gds` for the Game Design Document. - **Small scope + wants a captured artifact** (small tweak to an existing codebase, single doc to point at) → stay here and produce an *all-inclusive document*: lean spine plus inline Stories via the adapt-in Stories cluster. @@ -47,43 +69,50 @@ Before drafting, read the situation across four dimensions — they determine th Surface these honestly and let the user choose; if they prefer this skill anyway, proceed with the right-sized version. -Coach, do not quiz. Push hardest on PRD Discipline risks — unexamined assumptions, capability-vs-implementation confusion, term drift, scope creep, ambiguity for downstream readers. Suggest research if needed and have subagents use web search tools as needed. +### Working mode -**Working mode.** Once the situational read is complete, offer the user a choice before proceeding — one sentence per option: +Once the situational read is complete, offer the user a choice before proceeding (one sentence per option): - **Express:** resolve any remaining critical gaps in a short batch, then draft the full PRD at once. -- **Facilitative:** work through the sections that require PM thinking before drafting, using the techniques in `references/facilitation-guide.md`. Capture all decisions in the log, section to section. Draft after the key sections are walked. The goal is that the user has authored the thinking — not just answered intake questions. +- **Facilitative:** work through the sections that require PM thinking before drafting, using the techniques in `references/facilitation-guide.md`. Capture all decisions in the log, section to section. Draft after the key sections are walked. The goal is that the user has authored the thinking, not just answered intake questions. In both modes, resolve decisions conversationally rather than silently deferring them into `[ASSUMPTION]` tags. Only use `[ASSUMPTION]` when the answer requires research or external input the PM cannot provide in the moment. ## PRD Discipline +### Artifact shape + - **Features grouped, FRs nested.** Features open with behavioral description; FRs nested and numbered globally for stable IDs. Cross-cutting NFRs in their own section; skip traceability matrices. - **Capabilities, not implementation.** FRs describe what users or systems can do, not how. Tech choices go in addendum. +- **Right-size to purpose.** Section depth and adapt-in clusters follow project type and stakes; the template's adapt-in menu names the standard clusters. +- **Counter-metrics named.** When Success Metrics is present, name what NOT to optimize. + +### Substance + +- **Personas, when used, are research-grounded or marked `[ILLUSTRATIVE]`.** Invented detail is *persona theater*: false specificity the team builds for. Personas must drive decisions; two to four max. - **No innovation theater.** Don't fabricate novelty; add a differentiation section only when Discovery surfaced something genuinely novel. -- **Personas, when used, are research-grounded or marked `[ILLUSTRATIVE]`.** Invented detail is *persona theater* — false specificity the team builds for. Personas must drive decisions; two to four max. - **Domain awareness.** Regulatory or compliance constraints surface in the PRD, not deferred to architecture. -- **Right-size to purpose.** Section depth and adapt-in clusters follow project type and stakes — the template's adapt-in menu names the standard clusters. +- **Assumptions visible.** Inferences without direct user confirmation are tagged `[ASSUMPTION: ...]` inline and indexed at the end. + +### Honesty about scope + - **Non-Goals explicit.** Pair with inline `[NON-GOAL for MVP]` and `[v2 — out of MVP]` callouts so omissions aren't silently assumed. - **Never silently de-scope.** Nothing the user explicitly included drops without asking. Propose phasing; never impose it. -- **Counter-metrics named.** When Success Metrics is present, name what NOT to optimize. -- **Assumptions visible.** Inferences without direct user confirmation are tagged `[ASSUMPTION: ...]` inline and indexed at the end. - **`[NOTE FOR PM]` callouts** at decision points the user deferred or left tension on. ## Constraints -- **Persistence is near real-time.** Create the workspace (`prd.md` skeleton, `decision-log.md`) on disk the moment Create intent is confirmed; tell the user the path. -- **File roles.** `decision-log.md` — every decision, change, and version transition, in real time. `addendum.md` — depth that doesn't fit PRD shape: rejected alternatives, technical detail, ops/cost, competitive analysis. Capture technical-how detail to addendum immediately when the user volunteers it. +- **File roles.** `decision-log.md`: every decision, change, and version transition. `addendum.md`: depth that doesn't fit PRD shape (rejected alternatives, technical detail, ops/cost, competitive analysis). Capture technical-how detail to addendum immediately when the user volunteers it. - **Continuity across sessions.** If a prior draft exists in `{workflow.output_dir}`, offer to resume; surface open items first. - **Extract, don't ingest.** Never load source documents into the parent context wholesale. Delegate to subagents to extract what's relevant; the parent assembles from extracts. - **Downstream workflows run in fresh context.** This skill's output is `prd.md` (and optional `addendum.md`). Never invoke downstream workflows or produce separate handoff artifacts. ## Finalize -1. Decision log audit: walk `decision-log.md` with the user — each entry captured in PRD, in addendum, or set aside. +1. Decision log audit: walk `decision-log.md` with the user; each entry captured in PRD, in addendum, or set aside. 2. Input reconciliation: subagent per user-supplied input against `prd.md` + `addendum.md`; surface gaps, especially qualitative ideas (tone, voice, feel) the FR structure silently drops. Must happen before polish. -3. Discipline pass: validator subagent against `prd.md` with `{workflow.validation_checklist}`. Findings stay in-conversation — autofix obvious issues, ask on ambiguous ones. No report file is written. Resolve before polish. -4. Open-items review: triage all Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts. Surface only phase-blockers one at a time; resolve before calling the PRD ready. Log deferred items to `decision-log.md`. If phase-blocking count is high, flag it. +3. Discipline pass: validator subagent against `prd.md` with `{workflow.validation_checklist}`. Findings stay in-conversation; autofix obvious issues, ask on ambiguous ones. No report file is written. Resolve before polish. +4. Open-items review: triage all Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts. A phase-blocker is an open item that would make the PRD unsafe for the next phase of work (UX, architecture, epics); a non-blocker is deferrable to a later cycle with an owner and revisit condition. Surface only phase-blockers one at a time; resolve before calling the PRD ready. Log deferred items to `decision-log.md`. If phase-blocker count is high, flag it. 5. Polish: apply `{workflow.doc_standards}` to `prd.md` and `addendum.md` via parallel subagents. 6. External handoffs: execute `{workflow.external_handoffs}` entries; surface returned URLs/IDs. Skip and flag unavailable tools. 7. Record finalization to `decision-log.md`. Share all artifact paths. Invoke `bmad-help` to share possible steps. diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/references/facilitation-guide.md b/src/bmm-skills/2-plan-workflows/bmad-prd/references/facilitation-guide.md index e5cbb706b..df1a9bcf4 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/references/facilitation-guide.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/facilitation-guide.md @@ -2,6 +2,8 @@ Per-section conversation techniques for facilitative mode. Each entry names the coaching move that makes the section's conversation productive — not a checklist, a posture. Skip sections the PM has already resolved; spend more time where thinking is thin. +For symptom-based probes that apply across sections, load `references/probing.md` alongside this guide. + --- ## Users and Personas diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md b/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md new file mode 100644 index 000000000..968f878b9 --- /dev/null +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md @@ -0,0 +1,32 @@ +# Probing + +Loaded on entry to Discovery or Update. Symptom-based; `facilitation-guide.md` is section-based. Both apply. + +One probe per turn. When multiple gaps surface, pick the most load-bearing; record the others as Open Questions. + +## Seven probing categories + +| Trigger | Probe | Where it lands | +|---|---|---| +| Vague outcome ("better", "faster", "love it") | "What does it look like when it's working? How would you know?" | §7 Success Metrics, or Open Question | +| Evidence conflict (implied behavior change contradicts existing PRD/code/decision) | "Current behavior is X per [source]. Is the change to Y deliberate?" | `decision-log.md`; `[NOTE FOR PM]` in affected feature | +| Scope ambiguity ("all users", "the checkout flow") | "Does this apply to X? Is Y in or out?" | §5 Non-Goals or inline `[NON-GOAL]` | +| Missing failure UX (happy path only) | "What does the user see when X fails? Acceptable, or needs handling?" | Feature/FR; Open Question if undecided | +| Competing commitments (two requirements in tension) | "When A and B conflict, which wins?" | `decision-log.md` + counter-metric in §7 | +| Data availability (SM depends on data not verified to exist) | "Does the data exist today in measurable form? Baseline?" | SM definition or `[ASSUMPTION]` | +| Design readiness (UI implied without design) | "Reviewed design exists, or Open Question?" | Open Question; ref `bmad-create-ux-design` | + +## Six critical assumptions to scan before drafting + +Mechanism ambiguity, scope boundary, data availability, design readiness, dependency, timeline/commitment. When unresolved, tag `[ASSUMPTION: ...]` inline and surface in §9 Assumptions Index. + +## PRD / solution-design boundary + +A PRD probe asks WHAT, who, success, change. Not PRD probes (route to `addendum.md` or surface as an Open Question to `bmad-create-architecture`): + +- Mechanism / transport ("queue or API?") +- Build vs. consume ("build or vendor?") +- Internal architecture ("monolith vs. service?") +- Commercial-outcome decisions + +If a probe crosses into architecture, record in addendum or surface as an Open Question; don't pose it as a multi-choice question in the PRD session. From cf760ca2f4c3a698737a76fd8d5dcdf0420e44c9 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Thu, 14 May 2026 00:00:08 -0500 Subject: [PATCH 02/10] feat(bmad-prd): funnel discipline, UJ depth, and UX reframing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Template discipline for downstream AI extraction: - §3 Glossary: exact-use enforcement (FRs, UJs, SMs use Glossary terms verbatim) - §4 Features: FRs now use "#### FR-N: Name" heading with Realizes UJ-X cross-reference, testable consequences, and optional per-FR Out of Scope - §7 Success Metrics: SM-N / SM-CN numbering with Validates FR-X cross-reference User journeys: - §2.4 UJ format expanded from one-liner to named-persona mini-flow (persona, 3-5 steps, edge cases, optional capability surfacing); hobby can collapse to one-liners - Strip "job of UX" / "not this PRD" gatekeeping from template; depth is the team's call - Strengthen UX-as-input / UX-as-output patterns for bidirectional PRD <-> UX flow - SKILL.md Discovery Posture: push for two to three named-persona UJs in non-trivial scope Validation checklist: - Q-3 Traceability tightened to require Realizes UJ-X on FRs and Validates FR-X on SMs - Q-7 (new): FR testability — every FR has at least one testable consequence - S-1 Glossary integrity: now covers FR descriptions, consequences, UJ flows, SM definitions - S-2: SM added to ID continuity scope - S-5 (new): UJ persona linkage — every UJ names a persona by exact §2 label - STK-2 (new): UJ density gate — non-hobby scope needs at least two UJs --- .../2-plan-workflows/bmad-prd/SKILL.md | 6 +- .../bmad-prd/assets/prd-template.md | 57 ++++++++++++++----- .../assets/prd-validation-checklist.md | 9 ++- 3 files changed, 53 insertions(+), 19 deletions(-) diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md index c1e76cae1..6e9006bd8 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -44,7 +44,11 @@ How every turn runs, regardless of intent. ### Posture -Coach, do not quiz. Push hardest on PRD Discipline risks: unexamined assumptions, capability-vs-implementation confusion, term drift, scope creep, ambiguity for downstream readers. Suggest research if needed and have subagents use web search tools as needed. Load `references/probing.md` for the seven probing categories, critical-assumption scans, and the PRD / solution-design boundary; apply in Discovery and Update. +Coach, do not quiz. Push hardest on PRD Discipline risks: unexamined assumptions, capability-vs-implementation confusion, term drift, scope creep, ambiguity for downstream readers. Suggest research if needed and have subagents use web search tools as needed. + +Push for two to three named-persona user journeys even when the user does not propose them. UJs are how teams discover persona gaps, scope ambiguity, and missed failure handling. Solo/hobby scope can drop to one or none. + +Load `references/probing.md` for the seven probing categories, critical-assumption scans, and the PRD / solution-design boundary; apply in Discovery and Update. ### Brain dump diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md index 6efa2944b..cc9ec4cf2 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md @@ -34,15 +34,29 @@ updated: {YYYY-MM-DD} [Who this is explicitly not for in v1.] ### 2.4 Key User Journeys -*Named flows the product enables — one line each, numbered globally as UJ-1 through UJ-N for downstream traceability. Detailed flow design (steps, screens, edge flows) is the job of the UX workflow, not this PRD. Features in §4 may reference journeys by ID inline ("realizes UJ-3").* +*Named-persona flows the product enables. Numbered globally as UJ-1 through UJ-N. FRs reference journeys by ID inline ("realizes UJ-3"); SMs may also cross-reference. Depth is the team's call — the default below carries enough detail for downstream extraction; PMs may go deeper, including full UX-level detail with screens and micro-interactions, if they choose. If a UX doc already exists, mirror its UJ IDs here and point to the source.* -- **UJ-1** — [Named flow, one line: who does what, to what end.] -- **UJ-2** — ... +#### UJ-1: {Persona doing the thing} -[For hobby/utility projects, 1-3 journeys may be enough. For complex multi-feature products (onboarding, checkout, multi-step approvals), expand. For libraries/CLIs with minimal flow, reduce to a single line or collapse into §2.2 JTBD.] +**Persona:** {Name from §2.1, e.g. "Merchant Admin"} + +**Flow:** +1. {step} +2. {step} +3. {step} + +**Edge cases:** +- {real failure mode and what the user does next} + +**Capabilities surfaced:** *(optional)* +- The system must {capability}. → FR-N + +#### UJ-2: ... + +[Hobby/solo scope can collapse each UJ to a one-liner ("UJ-1 — short flow description"). For complex products with onboarding, checkout, multi-step approvals, etc., expand further. For libraries/CLIs with minimal flow, reduce to a single line or collapse into §2.2 JTBD.] ## 3. Glossary -*Downstream workflows and readers must use these terms exactly.* +*Downstream workflows and readers must use these terms exactly. FRs, UJs, and SMs use Glossary terms verbatim; introducing a synonym anywhere in the PRD is a discipline violation. If §4 introduces a new domain noun, add it to the Glossary in the same pass.* - **Term** — Definition. Relationships to other Glossary terms. Cardinality where relevant. - **Term** — ... @@ -53,11 +67,22 @@ updated: {YYYY-MM-DD} *Each subsection is a coherent feature: behavioral description first, FRs nested under it, optional feature-specific NFRs and notes. FRs are numbered globally (FR-1 through FR-N) so downstream artifacts have stable references even if features get reorganized. Reference user journeys by ID inline ("realizes UJ-2") where the chain matters.* ### 4.1 {Feature Name} -**Description:** [Behavioral narrative — how this feature works, who uses it, the user experience, edge cases. Use Glossary terms exactly. Embed inline `[ASSUMPTION: ...]` tags where you inferred without confirmation.] +**Description:** [Behavioral narrative — how this feature works, who uses it, the user experience, edge cases. Realizes UJ-X, UJ-Y. Use Glossary terms exactly. Embed inline `[ASSUMPTION: ...]` tags where you inferred without confirmation.] **Functional Requirements:** -- **FR-1** — [Actor] can [capability] [under conditions / with measurement]. -- **FR-2** — ... + +#### FR-1: {Short capability name} + +[Actor] can [capability] [under conditions]. Realizes UJ-X. + +**Consequences (testable):** +- {Specific testable condition, e.g. "System returns HTTP 429 when request rate exceeds 100/sec per merchant."} +- {Another testable condition.} + +**Out of Scope:** *(optional — what this FR explicitly does NOT cover)* +- {bound} + +#### FR-2: ... **Feature-specific NFRs:** *(only if any apply uniquely to this feature)* - Performance / security / accessibility / etc. specific to this feature. @@ -80,14 +105,16 @@ updated: {YYYY-MM-DD} ## 7. Success Metrics +*Each SM cross-references the FR(s) it validates. Counter-metrics counterbalance specific primary or secondary metrics.* + **Primary** -- Metric — definition, target. +- **SM-1**: Metric — definition, target. Validates FR-X, FR-Y. **Secondary** -- Metric — definition, target. +- **SM-2**: Metric — definition, target. Validates FR-Z. **Counter-metrics (do not optimize)** -- Metric — why this should *not* be optimized. +- **SM-C1**: Metric — why this should *not* be optimized. Counterbalances SM-1. [Length scales with stakes. Hobby/utility PRD: a single sentence may be enough ("Success: I use this weekly and don't abandon it after a month"). Public launch / enterprise: full quantitative breakdown with measurement methods. Counter-metrics are as load-bearing as primary metrics — they prevent the architect from optimizing the wrong thing and the dev from gaming the wrong target.] @@ -148,11 +175,11 @@ updated: {YYYY-MM-DD} - **The essential spine is the floor, not the ceiling.** A hobby PRD might keep all ten sections short. An enterprise PRD layers many clusters from the adapt-in menu. - **§3 Glossary before §4 Features.** Mechanics never introduce a new domain noun without adding it to the Glossary in the same pass. Persona, JTBD, and Journeys may use Glossary terms before §3 formally defines them — context is inferable; the Glossary is for downstream anchoring. -- **§2.4 Key User Journeys are brief.** One line each. Numbered globally (UJ-1 through UJ-N) so architecture, epics, stories, and tickets can reference them by stable ID. Detailed flow design happens in the UX workflow — not here. -- **§4 Features pattern at every scale.** Description → FRs nested → optional NFRs → optional notes. Hobby PRD: one short paragraph and three FRs per feature. Enterprise feature: multi-paragraph description, fifteen FRs, several feature-specific NFRs, open questions. Same shape, different depth. +- **§2.4 Key User Journeys carry signal.** Default shape is named-persona mini-flow (persona, 3-5 steps, edge cases, optional capability surfacing). PMs can go deeper, including full UX-level detail, if they choose. Hobby/solo scope can collapse to one-liners. UJs are how teams discover persona gaps, scope ambiguity, and missed failure handling — push for two to three in any non-trivial scope. +- **§4 Features pattern at every scale.** Description → FRs nested (each as `#### FR-N: Name` with testable consequences and optional per-FR Out of Scope) → optional feature-specific NFRs → optional notes. Hobby PRD: one short paragraph and three FRs per feature. Enterprise feature: multi-paragraph description, fifteen FRs, several feature-specific NFRs, open questions. Same shape, different depth. - **`[ASSUMPTION]`, `[NON-GOAL]`, `[v2 — out of MVP]`, `[NOTE FOR PM]` callouts are first-class.** They signal to downstream readers and the next session of work. Every `[ASSUMPTION]` lands in §9 Assumptions Index. -- **When UX is *input* to the PRD** (journeys already designed elsewhere): §2.4 names the journeys by ID and points to the existing UX doc. Reference, do not duplicate. -- **When UX is *output* of the PRD** (no UX work yet — downstream `bmad-create-ux-design` will produce it): §2.4 captures the PM's intent on which journeys exist; UX elaborates them into detailed flows downstream. +- **When UX is *input* to the PRD** (journeys already designed elsewhere): §2.4 mirrors the UX UJ IDs and points to the source doc. The PRD references, does not duplicate. Personas in §2.1 also mirror what the UX doc defined. +- **When UX is *output* of the PRD** (no UX work yet, may go to `bmad-create-ux-design` later): §2.4 carries the PM's understanding of the journeys with enough flow detail to be extractable downstream. UX elaboration adds screens, IA, and micro-interactions on top. - **§7 Success Metrics scales with stakes** but is always present. Counter-metrics matter as much as primary metrics — they shape what NOT to optimize. - **Small-scope all-inclusive option.** When scope is genuinely 1-2 stories and the user wants a single artifact instead of running a separate `bmad-create-story` workflow, add the adapt-in *Stories* cluster: lean §1-§6 plus inline §Stories at the end. The whole doc fits on a page or two. This is a valid PRD shape for tiny work — don't apologize for it. - **Adapt the section numbering.** The spine uses 0-9; adapt-in additions slot in wherever they read best (e.g., Aesthetic & Tone before §3 if branding is foundational, Compliance after §5 Non-Goals, Constraints & Guardrails between Features and Non-Goals, Stories at the very end after Assumptions Index). diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-validation-checklist.md b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-validation-checklist.md index a6b3cbef9..2f1429b02 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-validation-checklist.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-validation-checklist.md @@ -6,10 +6,11 @@ Loaded by the PRD validator subagent. For each item, return `{id, status: pass|f - **Q-1. Information density.** Sentences carry weight. Flag filler, hedging, and conversational padding. - **Q-2. Measurability.** Where measurement matters, FRs and Success Metrics are measurable; subjective adjectives flagged. Counter-metrics named when Success Metrics exist. -- **Q-3. Traceability.** Where the chain matters, FRs name their link to a user journey or success criterion inline. +- **Q-3. Traceability.** Every FR includes `Realizes UJ-X` referencing a UJ in §2.4. Every SM includes `Validates FR-X` referencing one or more FRs. Cross-references resolve. - **Q-4. Vision and JTBDs concrete.** Vision is specific and stands alone — not a generic feature list. JTBDs are audience-grounded, not abstract. - **Q-5. Non-Goals explicit.** A Non-Goals section is present where it would do real work; inline `[NON-GOAL]` and `[v2]` callouts where omissions would otherwise be silently assumed. - **Q-6. Dual-audience and self-contained.** Each section makes sense pulled out alone (cross-references via Glossary terms, not "see above"); the PRD is readable by humans and structured cleanly for downstream source-extraction by UX, architecture, and story-creation workflows. +- **Q-7. FR testability.** Every FR has at least one testable consequence (verifiable condition with measurable outcome). Flag hand-waves like "system handles X gracefully" or "reasonable performance." ## Discipline @@ -20,11 +21,13 @@ Loaded by the PRD validator subagent. For each item, return `{id, status: pass|f ## Structural integrity -- **S-1. Glossary integrity.** Every domain noun is defined in the Glossary and used identically throughout. Flag drift (case, plural, synonyms) and candidate missing-term entries. -- **S-2. ID continuity.** FR / UJ / Story IDs are contiguous, unique, and cross-references resolve. +- **S-1. Glossary integrity.** Every domain noun is defined in the Glossary and used identically throughout — including in FR descriptions, consequences, UJ flows, and SM definitions. Flag drift (case, plural, synonyms) and candidate missing-term entries. +- **S-2. ID continuity.** FR / UJ / SM / Story IDs are contiguous, unique, and cross-references resolve. - **S-3. Assumptions Index.** Every inline `[ASSUMPTION: ...]` appears in the Assumptions Index and vice versa. - **S-4. Open-items density.** Count Open Questions + `[ASSUMPTION]` + `[NOTE FOR PM]`. Red flag if density is high relative to the agreed stakes. +- **S-5. UJ persona linkage.** Every UJ names a persona from §2 by exact label. Flag floating UJs that don't tie to a defined persona. ## Stakes-gated - **STK-1. Required sections.** The PRD includes the sections the agreed stakes and product type warrant. +- **STK-2. UJ density.** For non-hobby/non-solo scope, at least two named-persona UJs present in §2.4. Hobby/solo scope is exempt. From 279ac0040f860b2762c35e1457658b8c6903c962 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Thu, 14 May 2026 00:02:43 -0500 Subject: [PATCH 03/10] docs(bmad-prd): anonymize validation-findings JSON example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace project-specific values (Plantsona prd_name, frozen timestamp, §16 location, premium-conversion finding) with generic placeholder content. Swap the example finding to demonstrate Q-7 FR testability so it doubles as a primer on the new checklist item. --- .../bmad-prd/references/validation-render.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/references/validation-render.md b/src/bmm-skills/2-plan-workflows/bmad-prd/references/validation-render.md index 5942dbe39..09df82423 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/references/validation-render.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/validation-render.md @@ -8,21 +8,21 @@ The subagent walks `{workflow.validation_checklist}` against `prd.md` (and `adde ```json { - "prd_name": "Plantsona", + "prd_name": "Example Product", "prd_path": "{doc_workspace}/prd.md", "checklist_path": "{workflow.validation_checklist}", - "timestamp": "2026-05-11T09:14:00", + "timestamp": "2026-01-15T09:14:00", "overall_synthesis": "2-3 sentences of judgment about the PRD's overall state — what holds up, what's at risk. Written by the subagent, not the parent.", "findings": [ { - "id": "Q-2", + "id": "Q-7", "category": "Quality", - "title": "Measurability", + "title": "FR testability", "status": "warn", "severity": "medium", - "location": "§16 Success Metrics, lines 408-422", - "note": "Success Metrics list is measurable but counter-metrics are named only for premium conversion. Other metrics lack paired counter-metrics.", - "suggested_fix": "Add counter-metrics for engagement (e.g., DAU/MAU) and seasonal cadence." + "location": "§4.2 Feature Name, FR-3", + "note": "FR-3's consequences include 'system handles errors gracefully' which is not testable.", + "suggested_fix": "Replace with a specific testable condition, e.g. 'System returns HTTP 4xx for invalid input within 200ms.'" } ] } From cf06efdd9491bd39384d946fd7a2aefa9fc36d19 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Fri, 15 May 2026 09:08:08 -0500 Subject: [PATCH 04/10] feat(bmad-prd): reviewer pass redesign and consolidate facilitation - finalize_reviewers TOML field replaces inline review lenses; entries follow the skill:/file:/plain-text prefix convention, resolved on-demand so reviewer data has zero context cost on runs that skip the pass. - Subagent contract: reviewers write to {doc_workspace}/review-{slug}.md and return summary-only (verdict, top findings, file path); parent never holds full review text. - Section-by-section walk-through UX at Finalize and Validate; user decides per finding whether to autofix, discuss, defer, or ignore. - Finalize entry names the sequence in one sentence so users understand the polish-last order. - Template philosophy moved from prd-template.md to SKILL.md PRD Discipline; template is now pure shape menu (preamble and Notes for facilitator stripped). - facilitation-guide.md content folded into SKILL.md Discovery posture (story-shape UJ walk, four MVP types, state-inference-don't-quiz); guide file deleted. --- .../2-plan-workflows/bmad-prd/SKILL.md | 16 ++-- .../bmad-prd/assets/prd-template.md | 20 +---- .../2-plan-workflows/bmad-prd/customize.toml | 23 ++++++ .../bmad-prd/references/facilitation-guide.md | 81 ------------------- 4 files changed, 34 insertions(+), 106 deletions(-) delete mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/references/facilitation-guide.md diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md index 6e9006bd8..f4be8564c 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -34,11 +34,11 @@ How every turn runs, regardless of intent. ## Intent Operating Modes -**Create.** A PRD the user is proud of, drawn out through real conversation. Discovery first, drafting second. Bind `{doc_workspace}` to a fresh folder at `{workflow.output_dir}/{workflow.output_folder_name}/` and write `prd.md` there with YAML frontmatter (title, created, updated); tell the user the workspace path. Version and state transitions live in `decision-log.md`. For Update and Validate, `{doc_workspace}` is the existing folder of the PRD being targeted. When drafting is complete, proceed to `## Finalize`. +**Create.** A PRD the user is proud of, drawn out through real conversation. Discovery first, drafting second. Bind `{doc_workspace}` to a fresh folder at `{workflow.output_dir}/{workflow.output_folder_name}/` and write `prd.md` there with YAML frontmatter (title, created, updated); tell the user the workspace path. Version and state transitions live in `decision-log.md`. When drafting is complete, proceed to `## Finalize`. -**Update.** Reconcile an existing PRD with a change signal. Orient via source extractors (see `## Constraints` → Extract, don't ingest) against the PRD, addendum, `decision-log.md`, and original inputs, then run the `## Discovery` posture against the change signal. Surface conflicts with prior decisions before changing: read `decision-log.md`, identify decisions touching the same area as the change, and for each, check whether the change reverses it, contradicts a stated assumption, or removes a non-goal; if so, raise it to the user before applying. If the change is fundamental (revises Vision or Target User), offer Create instead of patching. When changes are applied, proceed to `## Finalize`. +**Update.** Reconcile an existing PRD with a change signal. Orient via source extractors (see `## Constraints` → Extract, don't ingest) against the PRD, addendum, `decision-log.md`, and original inputs, then run the `## Discovery` posture against the change signal. Surface conflicts with prior decisions before changing: read `decision-log.md`, identify decisions touching the same area as the change, and for each, check whether the change reverses it, contradicts a stated assumption, or removes a non-goal; if so, raise it to the user before applying. Once changes are applied, proceed to `## Finalize`. -**Validate** (or *analyze*). Critique an existing PRD against `{workflow.validation_checklist}`. Standalone; does NOT enter `## Finalize`. Orient via source extractors against `decision-log.md` and any original inputs to give the validator context. Spawn the validator subagent against `prd.md` (and `addendum.md` if present); produce findings and a validation report per `references/validation-render.md`. Always offer to roll findings into an Update. +**Validate** (or *analyze*). Critique an existing PRD. Standalone; does NOT enter `## Finalize`. Orient via source extractors against `decision-log.md` and any original inputs. Assemble the reviewer gate menu: structural checklist validator (against `{workflow.validation_checklist}`) + each entry in `{finalize_reviewers}` (resolved on-demand from `customize.toml`) + any ad-hoc reviewers warranted by the PRD content (composed as plain-text entries on the fly). Present the menu; user picks all, a subset, or skip. Spawn the selection as parallel subagents against `prd.md` (and `addendum.md` if present), dispatching by prefix: `skill:NAME` invokes the named skill; `file:PATH` spawns an adversarial subagent applying the loaded file as the review prompt; plain-text entries are used directly as the subagent's prompt. **Subagent contract:** each reviewer writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary (verdict, top 2-3 findings as one-liners, file path); the parent never holds full review text in context. The structural validator additionally produces a validation report per `references/validation-render.md`. List all artifact paths and summaries to the user; offer a section-by-section walk through findings if they want it. Always offer to roll findings into an Update. ## Discovery @@ -48,6 +48,8 @@ Coach, do not quiz. Push hardest on PRD Discipline risks: unexamined assumptions Push for two to three named-persona user journeys even when the user does not propose them. UJs are how teams discover persona gaps, scope ambiguity, and missed failure handling. Solo/hobby scope can drop to one or none. +Facilitation moves to keep handy. For User Journeys, walk the story shape: opening scene, rising action, climax (the moment value is delivered), resolution; real edge cases surface at the climax, not as invented error states. For MVP scope, ask which kind of MVP this is before listing in/out: problem-solving (proves the problem is solved), experience (proves the interaction model), platform (proves the base others build on), or revenue (proves willingness to pay); each implies different scope logic. For feature decisions, state the inference and invite correction rather than quizzing the user ("I'm assuming X works like Y, is that right?" beats "should X work like Y or Z?"). + Load `references/probing.md` for the seven probing categories, critical-assumption scans, and the PRD / solution-design boundary; apply in Discovery and Update. ### Brain dump @@ -78,7 +80,7 @@ Surface these honestly and let the user choose; if they prefer this skill anyway Once the situational read is complete, offer the user a choice before proceeding (one sentence per option): - **Express:** resolve any remaining critical gaps in a short batch, then draft the full PRD at once. -- **Facilitative:** work through the sections that require PM thinking before drafting, using the techniques in `references/facilitation-guide.md`. Capture all decisions in the log, section to section. Draft after the key sections are walked. The goal is that the user has authored the thinking, not just answered intake questions. +- **Facilitative:** work through the sections that require PM thinking before drafting. Capture all decisions in the log, section to section. Draft after the key sections are walked. The goal is that the user has authored the thinking, not just answered intake questions. In both modes, resolve decisions conversationally rather than silently deferring them into `[ASSUMPTION]` tags. Only use `[ASSUMPTION]` when the answer requires research or external input the PM cannot provide in the moment. @@ -88,7 +90,7 @@ In both modes, resolve decisions conversationally rather than silently deferring - **Features grouped, FRs nested.** Features open with behavioral description; FRs nested and numbered globally for stable IDs. Cross-cutting NFRs in their own section; skip traceability matrices. - **Capabilities, not implementation.** FRs describe what users or systems can do, not how. Tech choices go in addendum. -- **Right-size to purpose.** Section depth and adapt-in clusters follow project type and stakes; the template's adapt-in menu names the standard clusters. +- **Right-size to purpose.** Load `{workflow.prd_template}` as the shape menu. Treat it as a menu, not a skeleton: drop, reorder, combine, or rename sections as the PRD needs; never include a section just because it appears. The essential spine is the floor, not the ceiling — hobby keeps it short, enterprise layers in clusters from the template's adapt-in menu. - **Counter-metrics named.** When Success Metrics is present, name what NOT to optimize. ### Substance @@ -113,9 +115,11 @@ In both modes, resolve decisions conversationally rather than silently deferring ## Finalize +At entry, name the sequence for the user in one sentence: walk the decision log, reconcile inputs, run the reviewer pass, resolve open items, then polish over the final content. Polish goes last so it does not have to redo work after reviewer fixes. + 1. Decision log audit: walk `decision-log.md` with the user; each entry captured in PRD, in addendum, or set aside. 2. Input reconciliation: subagent per user-supplied input against `prd.md` + `addendum.md`; surface gaps, especially qualitative ideas (tone, voice, feel) the FR structure silently drops. Must happen before polish. -3. Discipline pass: validator subagent against `prd.md` with `{workflow.validation_checklist}`. Findings stay in-conversation; autofix obvious issues, ask on ambiguous ones. No report file is written. Resolve before polish. +3. Reviewer pass. Assemble the gate menu: structural checklist validator (against `{workflow.validation_checklist}`) + each entry in `{finalize_reviewers}` (resolved on-demand from `customize.toml`) + any ad-hoc reviewers warranted by the PRD content (composed as plain-text entries on the fly). Gate UX is stakes-calibrated: hobby/solo scope may run defaults quietly or skip; higher stakes get the explicit menu with all, subset, or skip. Spawn the selection as parallel subagents against `prd.md`, dispatching by prefix: `skill:NAME` invokes the named skill; `file:PATH` spawns an adversarial subagent applying the loaded file as the review prompt; plain-text entries are used directly. **Subagent contract:** each reviewer writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary to the parent (verdict, top 2-3 findings as one-liners, file path). The parent never holds full review text in context. **Walk-through:** the parent groups findings by PRD section using each finding's location field (or by reviewer when section mapping is unclear); walks the user section by section, offering to open the full review document for any reviewer. Per finding, user picks autofix, discuss, defer to open items, or ignore. Hobby/solo scope can skip the walk and just print summaries. Resolve before polish. 4. Open-items review: triage all Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts. A phase-blocker is an open item that would make the PRD unsafe for the next phase of work (UX, architecture, epics); a non-blocker is deferrable to a later cycle with an owner and revisit condition. Surface only phase-blockers one at a time; resolve before calling the PRD ready. Log deferred items to `decision-log.md`. If phase-blocker count is high, flag it. 5. Polish: apply `{workflow.doc_standards}` to `prd.md` and `addendum.md` via parallel subagents. 6. External handoffs: execute `{workflow.external_handoffs}` entries; surface returned URLs/IDs. Skip and flag unavailable tools. diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md index cc9ec4cf2..ccdc3c52e 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md @@ -1,8 +1,4 @@ -# PRD Template — A Menu, Not a Skeleton - -This is a menu of sections the facilitator picks from based on what the product, the stakes, the audience, and the existing inputs actually need. Hobby projects use the essential spine and stop. Enterprise initiatives, regulated submissions, and consumer launches add clusters from the adapt-in menu below. **Never include a section just because it appears here.** Drop, reorder, rename, combine — whatever the PRD needs. - ---- +# PRD Template ## Essential Spine *(almost always present)* @@ -169,17 +165,3 @@ updated: {YYYY-MM-DD} ### Small-scope all-inclusive *(use when scope is 1-2 stories' worth and the user wants a single captured artifact — chosen during the Right-skill check in Discovery)* - **Stories** — story-level specs listed inline at the end of the doc. Each story: *"As a [persona], I can [action] [under conditions]. Acceptance: [testable criteria]."* Numbered Story-1, Story-2, ... for reference. Pair with very lean §1 Vision, §2 Target User (often just JTBD + one UJ), §3 Glossary (handful of terms), §4 Features (often a single feature), §6 MVP Scope (in/out very tight). The whole doc fits on a page or two and captures intent + implementable stories in one place. If the user doesn't want the captured artifact at all, `bmad-quick-dev` is the better path — this cluster is only for "I want a doc *and* the stories." ---- - -## Notes for the facilitator - -- **The essential spine is the floor, not the ceiling.** A hobby PRD might keep all ten sections short. An enterprise PRD layers many clusters from the adapt-in menu. -- **§3 Glossary before §4 Features.** Mechanics never introduce a new domain noun without adding it to the Glossary in the same pass. Persona, JTBD, and Journeys may use Glossary terms before §3 formally defines them — context is inferable; the Glossary is for downstream anchoring. -- **§2.4 Key User Journeys carry signal.** Default shape is named-persona mini-flow (persona, 3-5 steps, edge cases, optional capability surfacing). PMs can go deeper, including full UX-level detail, if they choose. Hobby/solo scope can collapse to one-liners. UJs are how teams discover persona gaps, scope ambiguity, and missed failure handling — push for two to three in any non-trivial scope. -- **§4 Features pattern at every scale.** Description → FRs nested (each as `#### FR-N: Name` with testable consequences and optional per-FR Out of Scope) → optional feature-specific NFRs → optional notes. Hobby PRD: one short paragraph and three FRs per feature. Enterprise feature: multi-paragraph description, fifteen FRs, several feature-specific NFRs, open questions. Same shape, different depth. -- **`[ASSUMPTION]`, `[NON-GOAL]`, `[v2 — out of MVP]`, `[NOTE FOR PM]` callouts are first-class.** They signal to downstream readers and the next session of work. Every `[ASSUMPTION]` lands in §9 Assumptions Index. -- **When UX is *input* to the PRD** (journeys already designed elsewhere): §2.4 mirrors the UX UJ IDs and points to the source doc. The PRD references, does not duplicate. Personas in §2.1 also mirror what the UX doc defined. -- **When UX is *output* of the PRD** (no UX work yet, may go to `bmad-create-ux-design` later): §2.4 carries the PM's understanding of the journeys with enough flow detail to be extractable downstream. UX elaboration adds screens, IA, and micro-interactions on top. -- **§7 Success Metrics scales with stakes** but is always present. Counter-metrics matter as much as primary metrics — they shape what NOT to optimize. -- **Small-scope all-inclusive option.** When scope is genuinely 1-2 stories and the user wants a single artifact instead of running a separate `bmad-create-story` workflow, add the adapt-in *Stories* cluster: lean §1-§6 plus inline §Stories at the end. The whole doc fits on a page or two. This is a valid PRD shape for tiny work — don't apologize for it. -- **Adapt the section numbering.** The spine uses 0-9; adapt-in additions slot in wherever they read best (e.g., Aesthetic & Tone before §3 if branding is foundational, Compliance after §5 Non-Goals, Constraints & Guardrails between Features and Non-Goals, Stories at the very end after Assumptions Index). diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml b/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml index 534bf7de4..6cda93020 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml @@ -111,3 +111,26 @@ external_sources = [] # "Mirror the PRD to Notion via notion:create_page (database_id='abc123', title='PRD: '+{project_name})." # "When the PRD references a parent initiative, link via corp:jira_link on the epic key in frontmatter." external_handoffs = [] + +# --- Finalize reviewers --- +# Reviewers spawned at Finalize step 3 (and at the Validate intent) alongside +# the structural checklist validator. The authoring skill assembles the gate +# menu (validator + these reviewers + any ad-hoc reviewers it judges warranted +# by the artifact content) and lets the user pick all, a subset, or skip. Gate +# UX is stakes-calibrated: hobby/solo scope may run defaults quietly or skip; +# higher stakes get the explicit menu. +# +# Entries follow the standard prefix convention (same as persistent_facts and +# doc_standards): +# "skill:NAME" invoke the named review skill as a subagent against prd.md +# "file:PATH" load the file as a review prompt; spawn an adversarial +# subagent applying that prompt to prd.md +# plain text use the text directly as the subagent's review prompt +# +# Override TOML may append additional reviewers. Arrays append per BMad rules. +# +# Resolved on-demand by the authoring skill (not pulled at activation): only +# when entering the Validate intent or assembling the gate at Finalize step 3. +finalize_reviewers = [ + "skill:bmad-review-adversarial-general", +] diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/references/facilitation-guide.md b/src/bmm-skills/2-plan-workflows/bmad-prd/references/facilitation-guide.md deleted file mode 100644 index df1a9bcf4..000000000 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/references/facilitation-guide.md +++ /dev/null @@ -1,81 +0,0 @@ -# PRD Facilitation Guide - -Per-section conversation techniques for facilitative mode. Each entry names the coaching move that makes the section's conversation productive — not a checklist, a posture. Skip sections the PM has already resolved; spend more time where thinking is thin. - -For symptom-based probes that apply across sections, load `references/probing.md` alongside this guide. - ---- - -## Users and Personas - -**The move:** Ground personas in real people, not archetypes. - -Ask the PM to describe a specific person they have observed or talked to — not a type, an actual human. "Who is the clerk at your store? Tell me about them." Invented detail (name, age, backstory from nowhere) is persona theater — the team builds for a fiction. If the PM says "someone like..." push gently: "Is there a real person you're thinking of?" - -Once grounded: what does that person want to accomplish in the time they interact with this product? What would make them say this is easier than what they do today? What would make them abandon it? - -For the remote user or secondary persona: same grounding, different question — what question do they need answered in under ten seconds, and what do they do if they can't get it? - -Mark anything the PM could not ground in observation as `[ILLUSTRATIVE]` — and note it's a hypothesis to validate, not a spec to build for. - ---- - -## Core User Journeys - -**The move:** Story structure, not use-case list. - -For each primary journey, walk through four beats: - -- **Opening scene** — where do we meet this person, what is their situation right now, what pain or need is present? -- **Rising action** — what steps do they take, what do they discover or decide along the way? -- **Climax** — the moment the product delivers real value; the thing they could not do before -- **Resolution** — what is their new reality; how is their situation different? - -After each journey: what could go wrong at the climax? What is the recovery path? This is where edge cases that matter surface — not invented error states, but real failure modes for this person. - -Explicitly name what capability each journey reveals. "This journey requires the operator to log an entry with no internet — which means we need a decision on whether that's in or out of MVP." Journeys produce capability requirements; make the link visible. - ---- - -## Key Feature Decisions - -**The move:** Surface the assumptions that would otherwise be silent. - -Before the draft exists, there are decisions the agent would silently make and the PM would never know were made. These are the ones worth a thirty-second conversation: - -- Decisions that drive the core UX model (e.g., one record per day vs. many; who can edit vs. view; what happens when the expected input doesn't exist) -- Decisions where the "obvious" choice has real consequences the PM may not have considered -- Decisions that, if wrong, require structural changes to fix later - -For each: state what you inferred, name the alternative, ask which is right. Do not present options as a quiz — present your inference and invite correction. "I'm assuming one sales tally per day replaces rather than adds. Is that right, or should the operator be able to log multiple?" Resolve and move on. Only tag as `[ASSUMPTION]` when the answer requires external input or research the PM cannot provide now. - ---- - -## Scope Boundary - -**The move:** Establish MVP philosophy before listing features. - -Before asking what is in or out, ask what kind of MVP this is: - -- **Problem-solving MVP** — the minimum that proves the core problem is solved; rough edges acceptable -- **Experience MVP** — the minimum that proves the interaction model works; quality matters -- **Platform MVP** — the minimum infrastructure other things can build on; completeness of the base matters -- **Revenue MVP** — the minimum someone will pay for; business viability is the test - -The answer changes what "minimum" means. A problem-solving MVP for a personal-use tool has different scope logic than an experience MVP aimed at non-tech-savvy users who will bounce at the first confusion. - -Once the philosophy is named, non-goals do as much work as in-scope items. Probe for the things the PM is tempted to add. "What keeps almost making it onto the list?" For each: is it truly out of MVP, or does it need to be in because the MVP fails without it? - ---- - -## Success Metrics - -**The move:** Push every adjective to a measurement. - -"Users will love it" — what does that mean in behavior? "It'll be fast" — fast at what, for whom, measured how? "Good adoption" — what percentage, by when, doing what? Every quality claim needs a measurement or it is not a success criterion, it is a wish. - -For each metric surfaced: connect it back to the product's differentiator. If the differentiator is simplicity for non-tech users, the primary metric should measure whether non-tech users successfully complete the core action without help — not session count or feature usage breadth. - -Name counter-metrics explicitly — what this product should *not* optimize for. These prevent the wrong thing being built: more entries per day is not better if the goal is accurate daily records; longer dashboard sessions may indicate a broken IA, not high engagement. Counter-metrics are as load-bearing as primary metrics for downstream readers. - -For low-stakes or personal-use products: one sentence is enough. "Success: I use this daily and it replaces the notebook within a month." Do not impose metric rigor where the stakes do not warrant it. From 966ed2572eb8871c68abfc4fcd32182babe5a963 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Fri, 15 May 2026 12:02:43 -0500 Subject: [PATCH 05/10] feat(bmad-prd): tighten SKILL.md, extract Reviewer Gate and Validate playbook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - SKILL.md: trim activation/posture/discovery bloat; sharpen Right-skill check; extract Reviewer Gate to its own section (dedup with Finalize step 3 and Validate intent). - references/validate.md: rename from validation-render.md and expand to the full Validate intent playbook (orient, run gate, structural validator pipeline, render, close). - references/probing.md: drop stale facilitation-guide.md reference. - assets/prd-template.md: redesign §2.4 User Journeys with named-scene default shape, worked example, and scope dial. --- .../2-plan-workflows/bmad-prd/SKILL.md | 51 +++++++++++-------- .../bmad-prd/assets/prd-template.md | 31 +++++------ .../bmad-prd/references/probing.md | 2 +- .../{validation-render.md => validate.md} | 30 ++++++++--- 4 files changed, 70 insertions(+), 44 deletions(-) rename src/bmm-skills/2-plan-workflows/bmad-prd/references/{validation-render.md => validate.md} (50%) diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md index f4be8564c..67d045291 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -15,22 +15,19 @@ You are an expert PM facilitator. The user has an idea that needs to be captured 3. Treat every entry in `{workflow.persistent_facts}` as foundational context. Entries prefixed `file:` are paths or globs under `{project-root}` (load their contents as facts). All others are facts verbatim. 4. Note `{workflow.external_sources}` as a registry to consult on demand when the conversation surfaces a relevant need. Do not query preemptively. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap. 5. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. -6. Detect mode and intent. If headless (no interactive user), read `references/headless.md` and follow it for the whole run with matched intent. If interactive, greet `{user_name}` in `{communication_language}` and note that `bmad-party-mode` (multi-agent perspectives) and `bmad-advanced-elicitation` (deeper exploration) can be invoked at any point. Detect intent from the user's first message and existing files: - - **Create**: no existing PRD resolves; verbs like start, draft, make, build. - - **Update**: an existing `prd.md` is referenced or located; verbs like update, edit, change, revise, patch. - - **Validate** (or *analyze*): verbs like validate, review, analyze, audit, check; or the user supplies an artifact and asks for feedback. +6. Detect mode and intent. If headless, read `references/headless.md` and follow it for the whole run. Otherwise greet `{user_name}` in `{communication_language}`. Detect intent from the user's first message and existing files: + - **Create**: no existing PRD resolves. + - **Update**: an existing `prd.md` is referenced or located. + - **Validate** (or *analyze*): user supplies an artifact and asks for feedback, or wants critique without changes. If two intents could apply, confirm with one question. 7. Execute each entry in `{workflow.activation_steps_append}` in order. ## Session Posture -How every turn runs, regardless of intent. - - Plain and direct. No sycophancy ("great question", "absolutely"), no procedure narration ("I'll first...", "let me now..."), no length-nudge phrases ("concise", "brief"). - Record as the user surfaces it. Decisions, assumptions, open questions land in `decision-log.md` or inline tags before the next turn. - Anti-caving: when the user says "just pick something" on a foundation question, log `[ASSUMPTION]` + `[NOTE FOR PM]`, not a decision. When evidence is thin, say so; don't draft around the gap. When a validator surfaces a blocker, fix or log; don't rationalize. -- Match the user's register. ## Intent Operating Modes @@ -38,13 +35,13 @@ How every turn runs, regardless of intent. **Update.** Reconcile an existing PRD with a change signal. Orient via source extractors (see `## Constraints` → Extract, don't ingest) against the PRD, addendum, `decision-log.md`, and original inputs, then run the `## Discovery` posture against the change signal. Surface conflicts with prior decisions before changing: read `decision-log.md`, identify decisions touching the same area as the change, and for each, check whether the change reverses it, contradicts a stated assumption, or removes a non-goal; if so, raise it to the user before applying. Once changes are applied, proceed to `## Finalize`. -**Validate** (or *analyze*). Critique an existing PRD. Standalone; does NOT enter `## Finalize`. Orient via source extractors against `decision-log.md` and any original inputs. Assemble the reviewer gate menu: structural checklist validator (against `{workflow.validation_checklist}`) + each entry in `{finalize_reviewers}` (resolved on-demand from `customize.toml`) + any ad-hoc reviewers warranted by the PRD content (composed as plain-text entries on the fly). Present the menu; user picks all, a subset, or skip. Spawn the selection as parallel subagents against `prd.md` (and `addendum.md` if present), dispatching by prefix: `skill:NAME` invokes the named skill; `file:PATH` spawns an adversarial subagent applying the loaded file as the review prompt; plain-text entries are used directly as the subagent's prompt. **Subagent contract:** each reviewer writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary (verdict, top 2-3 findings as one-liners, file path); the parent never holds full review text in context. The structural validator additionally produces a validation report per `references/validation-render.md`. List all artifact paths and summaries to the user; offer a section-by-section walk through findings if they want it. Always offer to roll findings into an Update. +**Validate** (or *analyze*). Critique an existing PRD without changing it. Load `references/validate.md` and follow it. ## Discovery ### Posture -Coach, do not quiz. Push hardest on PRD Discipline risks: unexamined assumptions, capability-vs-implementation confusion, term drift, scope creep, ambiguity for downstream readers. Suggest research if needed and have subagents use web search tools as needed. +Coach, do not quiz. Push hardest on PRD Discipline risks: unexamined assumptions, capability-vs-implementation confusion, term drift, scope creep, ambiguity for downstream readers. Push for two to three named-persona user journeys even when the user does not propose them. UJs are how teams discover persona gaps, scope ambiguity, and missed failure handling. Solo/hobby scope can drop to one or none. @@ -63,17 +60,15 @@ Before drafting, read the situation across four dimensions; they determine the P - **Stakes.** Calibrates rigor, section depth, and which adapt-in clusters apply. - **Audience.** Drives tone, evidence requirements, and approval sections. - **Existing inputs.** Existing artifacts mean those parts of the PRD reference, not relitigate. When project-context, prior PRDs, or existing UX/architecture are present, this is brownfield; frame Discovery around what is new or changing. -- **Downstream depth.** Whole spec for a small build, or top of a chain through UX → architecture → epics → stories? Affects how much the PRD encodes vs. defers. +- **Downstream depth.** Standalone spec, or top of a UX → architecture → epics → stories chain? Affects how much to encode vs. defer. ### Right-skill check -Once the situation is read, sanity-check that PRD is the best tool. Three cases where it isn't: +Sanity-check that PRD is the right tool before drafting: -- **Games** → suggest `bmad-gds` for the Game Design Document. -- **Small scope + wants a captured artifact** (small tweak to an existing codebase, single doc to point at) → stay here and produce an *all-inclusive document*: lean spine plus inline Stories via the adapt-in Stories cluster. -- **Express implementation** (wants to build now, no planning chain or captured artifact needed) → suggest `bmad-quick-dev`. - -Surface these honestly and let the user choose; if they prefer this skill anyway, proceed with the right-sized version. +- **Games** → suggest BMad Game Dev Studio (GDS). +- **Small scope, wants a captured artifact** (small tweak to existing codebase, single doc to point at) → stay here, use the adapt-in Stories cluster for an all-inclusive document. +- **Express implementation** (build now, no planning chain, no captured artifact, small intent or story) → suggest skill `bmad-quick-dev` instead. ### Working mode @@ -82,7 +77,7 @@ Once the situational read is complete, offer the user a choice before proceeding - **Express:** resolve any remaining critical gaps in a short batch, then draft the full PRD at once. - **Facilitative:** work through the sections that require PM thinking before drafting. Capture all decisions in the log, section to section. Draft after the key sections are walked. The goal is that the user has authored the thinking, not just answered intake questions. -In both modes, resolve decisions conversationally rather than silently deferring them into `[ASSUMPTION]` tags. Only use `[ASSUMPTION]` when the answer requires research or external input the PM cannot provide in the moment. +In both modes, resolve decisions conversationally rather than silently deferring them into `[ASSUMPTION]` tags. Only use `[ASSUMPTION]` when the answer requires research or external input they cannot provide in the moment. ## PRD Discipline @@ -108,10 +103,24 @@ In both modes, resolve decisions conversationally rather than silently deferring ## Constraints -- **File roles.** `decision-log.md`: every decision, change, and version transition. `addendum.md`: depth that doesn't fit PRD shape (rejected alternatives, technical detail, ops/cost, competitive analysis). Capture technical-how detail to addendum immediately when the user volunteers it. +- **File roles.** `decision-log.md`: every decision, change, and version transition. `addendum.md`: Technical-how detail to addendum immediately when the user volunteers it. - **Continuity across sessions.** If a prior draft exists in `{workflow.output_dir}`, offer to resume; surface open items first. - **Extract, don't ingest.** Never load source documents into the parent context wholesale. Delegate to subagents to extract what's relevant; the parent assembles from extracts. -- **Downstream workflows run in fresh context.** This skill's output is `prd.md` (and optional `addendum.md`). Never invoke downstream workflows or produce separate handoff artifacts. + +## Reviewer Gate + +Run during the Validate intent and at Finalize step 3. + +**Menu.** Structural checklist validator (against `{workflow.validation_checklist}`) + each entry in `{finalize_reviewers}` (resolved on-demand from `customize.toml`) + any ad-hoc reviewers warranted by the artifact content (composed as plain-text entries on the fly). Stakes-calibrated: hobby/solo may run defaults quietly or skip; higher stakes get the explicit menu with all/subset/skip. + +**Dispatch.** Spawn the selection as parallel subagents against `prd.md` (and `addendum.md` if present), by prefix: +- `skill:NAME` — invoke named skill. +- `file:PATH` — spawn an adversarial subagent giving the agent the file path to use as review lens. +- `text` — follow the instructions use directly as the subagent's prompt. + +**Subagent contract.** Each reviewer writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary (verdict, top 2-5 findings succinct, file path). The parent never holds full review text unless tool does not support subagents. Under Validate intent, the structural validator additionally runs the rendering pipeline in `references/validate.md`. + +**Walk-through.** Present the findings in an organized facilitative fashion. Per finding user can choose to: autofix, discuss, defer to open items, or ignore. ## Finalize @@ -119,8 +128,8 @@ At entry, name the sequence for the user in one sentence: walk the decision log, 1. Decision log audit: walk `decision-log.md` with the user; each entry captured in PRD, in addendum, or set aside. 2. Input reconciliation: subagent per user-supplied input against `prd.md` + `addendum.md`; surface gaps, especially qualitative ideas (tone, voice, feel) the FR structure silently drops. Must happen before polish. -3. Reviewer pass. Assemble the gate menu: structural checklist validator (against `{workflow.validation_checklist}`) + each entry in `{finalize_reviewers}` (resolved on-demand from `customize.toml`) + any ad-hoc reviewers warranted by the PRD content (composed as plain-text entries on the fly). Gate UX is stakes-calibrated: hobby/solo scope may run defaults quietly or skip; higher stakes get the explicit menu with all, subset, or skip. Spawn the selection as parallel subagents against `prd.md`, dispatching by prefix: `skill:NAME` invokes the named skill; `file:PATH` spawns an adversarial subagent applying the loaded file as the review prompt; plain-text entries are used directly. **Subagent contract:** each reviewer writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary to the parent (verdict, top 2-3 findings as one-liners, file path). The parent never holds full review text in context. **Walk-through:** the parent groups findings by PRD section using each finding's location field (or by reviewer when section mapping is unclear); walks the user section by section, offering to open the full review document for any reviewer. Per finding, user picks autofix, discuss, defer to open items, or ignore. Hobby/solo scope can skip the walk and just print summaries. Resolve before polish. -4. Open-items review: triage all Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts. A phase-blocker is an open item that would make the PRD unsafe for the next phase of work (UX, architecture, epics); a non-blocker is deferrable to a later cycle with an owner and revisit condition. Surface only phase-blockers one at a time; resolve before calling the PRD ready. Log deferred items to `decision-log.md`. If phase-blocker count is high, flag it. +3. Reviewer pass: run the `## Reviewer Gate` against `prd.md`. Resolve before polish. +4. Triage all Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts. A phase-blocker is an open item that would make the PRD unsafe for the next phase of work (UX, architecture, epics); a non-blocker is deferrable to a later cycle with an owner and revisit condition. Surface only phase-blockers one at a time; resolve before calling the PRD ready. Log deferred items to `decision-log.md`. If phase-blocker count is high, flag it. 5. Polish: apply `{workflow.doc_standards}` to `prd.md` and `addendum.md` via parallel subagents. 6. External handoffs: execute `{workflow.external_handoffs}` entries; surface returned URLs/IDs. Skip and flag unavailable tools. 7. Record finalization to `decision-log.md`. Share all artifact paths. Invoke `bmad-help` to share possible steps. diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md index ccdc3c52e..2d2e265b1 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md @@ -30,26 +30,27 @@ updated: {YYYY-MM-DD} [Who this is explicitly not for in v1.] ### 2.4 Key User Journeys -*Named-persona flows the product enables. Numbered globally as UJ-1 through UJ-N. FRs reference journeys by ID inline ("realizes UJ-3"); SMs may also cross-reference. Depth is the team's call — the default below carries enough detail for downstream extraction; PMs may go deeper, including full UX-level detail with screens and micro-interactions, if they choose. If a UX doc already exists, mirror its UJ IDs here and point to the source.* +*Named-persona narratives the product enables. Numbered globally as UJ-1 through UJ-N. FRs reference journeys by ID inline ("realizes UJ-3"); SMs may also cross-reference. If a UX doc already exists, mirror its UJ IDs here and point to the source.* -#### UJ-1: {Persona doing the thing} +**Default shape:** a named scene with entry state, path, climax, and resolution. Each beat forces specificity the team would otherwise leave implicit — auth assumptions, screen order, what tells the user value landed. Read together as a short narrative; the example below shows the form. -**Persona:** {Name from §2.1, e.g. "Merchant Admin"} +- **UJ-1. {One-line title — persona doing the thing.}** + - **Persona + context:** one line, grounded enough to explain the *why*. + - **Entry state:** authenticated? which surface? coming from where? + - **Path:** 3-5 concrete beats — taps, screens, decisions. + - **Climax:** the moment value is delivered and how the user knows. + - **Resolution:** state they're left in, what's next. + - **Edge case** *(optional)*: one real failure mode and what the user does next. -**Flow:** -1. {step} -2. {step} -3. {step} + *Written out, that becomes:* + > **UJ-3. Priya checks the trip damage before she's even home.** + > Priya, budgeting on a single income with a new baby, finishes a grocery run and gets in the car. Already authenticated via biometric on a previous session. She opens the app, taps the FAB camera, and scans the receipt. The app OCRs the total and shows a single-screen overlay: this trip $84.20, weekly cap $250, $172.10 remaining, three days left in the week. She closes the app and drives home. **Edge case:** if she scanned a receipt earlier today, the app asks whether this replaces or adds to that trip before counting it against the cap. -**Edge cases:** -- {real failure mode and what the user does next} +- **UJ-2. ...** -**Capabilities surfaced:** *(optional)* -- The system must {capability}. → FR-N - -#### UJ-2: ... - -[Hobby/solo scope can collapse each UJ to a one-liner ("UJ-1 — short flow description"). For complex products with onboarding, checkout, multi-step approvals, etc., expand further. For libraries/CLIs with minimal flow, reduce to a single line or collapse into §2.2 JTBD.] +**Scope dial:** +- **Lighter** — hobby/solo, library/CLI, or when the UJ is essentially a JTBD restated: a single sentence works (`{Persona}, {context}, {what they do and why}.`). +- **Heavier** — auth, multi-device handoff, complex navigation, or anything feeding downstream UX/architecture: add a numbered Flow, an Edge cases list, and a capability → FR mapping (`The system must {capability}. → FR-N`). ## 3. Glossary *Downstream workflows and readers must use these terms exactly. FRs, UJs, and SMs use Glossary terms verbatim; introducing a synonym anywhere in the PRD is a discipline violation. If §4 introduces a new domain noun, add it to the Glossary in the same pass.* diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md b/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md index 968f878b9..03b01cc5b 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md @@ -1,6 +1,6 @@ # Probing -Loaded on entry to Discovery or Update. Symptom-based; `facilitation-guide.md` is section-based. Both apply. +Loaded on entry to Discovery or Update. One probe per turn. When multiple gaps surface, pick the most load-bearing; record the others as Open Questions. diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/references/validation-render.md b/src/bmm-skills/2-plan-workflows/bmad-prd/references/validate.md similarity index 50% rename from src/bmm-skills/2-plan-workflows/bmad-prd/references/validation-render.md rename to src/bmm-skills/2-plan-workflows/bmad-prd/references/validate.md index 09df82423..fe1e2380f 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/references/validation-render.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/validate.md @@ -1,10 +1,22 @@ -# Validation Rendering +# Validate -How the validator subagent's findings become a validation report. Loaded only when the user has explicitly asked for analysis — either Validate intent or a mid-session report request. The Finalize discipline pass during Create/Update does NOT render a report; its findings stay in-conversation. +The full Validate intent playbook. Also covers the structural-validator rendering pipeline used during mid-session report requests. -## Validator subagent output contract +Critique an existing PRD without changing it. Standalone; does NOT enter `## Finalize`. -The subagent walks `{workflow.validation_checklist}` against `prd.md` (and `addendum.md` if present) and writes `{doc_workspace}/validation-findings.json`: +## Orient + +Source-extract against `decision-log.md`, any original inputs, and the PRD/addendum themselves. Delegate to subagents per `## Constraints` → Extract, don't ingest; the parent assembles from extracts. + +## Run the Reviewer Gate + +Run the `## Reviewer Gate` (in SKILL.md) against `prd.md` (and `addendum.md` if present). The gate handles menu assembly, parallel dispatch, the subagent contract, and the section-by-section walk-through. + +The structural checklist validator is one entry in the gate menu; under Validate intent it additionally runs the rendering pipeline below. The Finalize discipline pass during Create/Update does NOT render a report — its findings stay in-conversation. + +## Structural validator pipeline + +The structural validator subagent walks `{workflow.validation_checklist}` against `prd.md` (and `addendum.md` if present) and writes findings to `{doc_workspace}/validation-findings.json`: ```json { @@ -39,7 +51,7 @@ Per-finding fields: - `note` (optional) — the finding itself, in one or two sentences. - `suggested_fix` (optional) — concrete next action. -## Rendering invocation +### Render After the subagent writes findings: @@ -53,6 +65,10 @@ python3 {skill-root}/scripts/render-validation-html.py \ Include `--open` for interactive runs (auto-opens in default browser). Omit `--open` in headless runs. -The script writes two artifacts side-by-side: the HTML report at `--output`, and a markdown companion at the same path with `.md` extension (e.g. `validation-report.md`). Both are always produced when the script runs — trigger gating happens upstream (the script is only invoked when the user has asked for analysis). It computes pass/warn/fail/na counts, derives a grade (Excellent / Good / Fair / Poor) from critical-fail and total-fail counts, renders an inline SVG score bar in the HTML, groups findings by category, and returns a one-line JSON summary on stdout: `{"output": "...", "markdown": "...", "grade": "...", "stats": {...}}`. +The script writes two artifacts side-by-side: the HTML report at `--output`, and a markdown companion at the same path with `.md` extension (e.g. `validation-report.md`). Both are always produced when the script runs. It computes pass/warn/fail/na counts, derives a grade (Excellent / Good / Fair / Poor) from critical-fail and total-fail counts, renders an inline SVG score bar in the HTML, groups findings by category, and returns a one-line JSON summary on stdout: `{"output": "...", "markdown": "...", "grade": "...", "stats": {...}}`. -Re-running validation overwrites the existing report files in place. Markdown form is what Update mode reads when rolling findings into a revision. +Re-running validation overwrites existing report files in place. Markdown form is what Update mode reads when rolling findings into a revision. + +## Close + +Surface all artifact paths and summaries to the user. The Reviewer Gate's walk-through covers section-by-section review of findings; the rendered HTML/markdown report is the persistent artifact. Always offer to roll findings into an Update; Validate itself does not change `prd.md`. From 71bac22a608d6d98403279ad0c55213bca99315a Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Fri, 15 May 2026 15:44:41 -0500 Subject: [PATCH 06/10] fix(bmad-prd): make Brain dump a hard first-move rule Discovery was being skipped: the LLM treated the user's opening message as the full picture and jumped to multiple-choice intake. Strengthen the ordering so Brain dump always comes first for Create and Update, before any questions or working-mode choices. - Add explicit Discovery ordering at the section top. - Rewrite Brain dump as a non-negotiable first move with an anti- pattern callout naming the exact failure mode. - Add timing prefix to Working mode reinforcing the order. --- src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md index 67d045291..96c863cc8 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -39,6 +39,8 @@ You are an expert PM facilitator. The user has an idea that needs to be captured ## Discovery +For Create and Update intent, run Discovery in this order: **Brain dump → Four-dimension read → Right-skill check → Working mode.** Never skip ahead. + ### Posture Coach, do not quiz. Push hardest on PRD Discipline risks: unexamined assumptions, capability-vs-implementation confusion, term drift, scope creep, ambiguity for downstream readers. @@ -51,7 +53,9 @@ Load `references/probing.md` for the seven probing categories, critical-assumpti ### Brain dump -Open with space for the full picture: invite a brain dump, inputs, ideas, WHY they are doing this. Read what exists first; ask only what is missing. After the dump, a simple "anything else?" often surfaces what they almost forgot. +**Always the first move for Create and Update intent, no exceptions.** Even when the user opens with a few sentences of context, that is intake — not the brain dump. Before any questions (especially multiple-choice), explicitly invite them to unload everything they have in mind: full picture, inputs, ideas, WHY. Read what exists first; ask only what is missing *after* the dump. A simple "anything else?" often surfaces what they almost forgot. + +Anti-pattern: treating the user's opening message as the full picture and jumping to assumptions, intake questions, or working-mode choices. The user may have a lot more to say; ask before assuming. The more they give us, the more we have to work with and the faster the process will be also for the user as we can help tighten and organize their own thinking and creativity as part of the PRD process as the user is the expert. ### Four-dimension read @@ -72,7 +76,7 @@ Sanity-check that PRD is the right tool before drafting: ### Working mode -Once the situational read is complete, offer the user a choice before proceeding (one sentence per option): +Working-mode choice comes *after* the brain dump and four-dimension read, never before. Once the situational read is complete, offer the user a choice before proceeding (one sentence per option): - **Express:** resolve any remaining critical gaps in a short batch, then draft the full PRD at once. - **Facilitative:** work through the sections that require PM thinking before drafting. Capture all decisions in the log, section to section. Draft after the key sections are walked. The goal is that the user has authored the thinking, not just answered intake questions. From a586c0fa64504ce0f68b74793c0cfd439a65b7fb Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Fri, 15 May 2026 17:29:04 -0500 Subject: [PATCH 07/10] refactor(bmad-prd): aggressive trim and quality fixes from analysis SKILL.md cut 49% (143 -> 84 lines); references/validate.md 35%; references/headless.md 22%. Package-wide ~21% reduction. Customization sweep: - {finalize_reviewers} -> {workflow.finalize_reviewers} (was a silent override no-op) - Add canonical ## Conventions block - Rename decision-log.md -> .decision-log.md across SKILL, refs, schemas - customize.toml: validation_checklist -> validation_checklist_template, output_dir -> prd_output_path, output_folder_name -> run_folder_pattern; lifecycle comments on external_sources / external_handoffs New behavior: - Activation step 4: explicit by-name greeting using {user_name}, {communication_language} persisted for every turn (not just greeting) - Right-skill scan on first message before brain dump - Neutral defaults when config.yaml is missing; never block on it - Headless: Detection section + per-intent Inputs section + 'partial' status semantics + Update conflict-override rationale - Brownfield Update bootstraps .decision-log.md via subagent when absent - Reviewer Gate findings-overwhelm fix: tiered surfacing (verdict -> critical/high -> medium/low rolled into tail) - Discovery edge cases: conditional MVP question, persona/UJ push contextually triggered, working modes renamed as outcomes (Fast path / Coaching path) - Subagent discipline: Finalize step 2 return-format contract, step 5 structure->prose ordering, explicit no-subagent fallback Tests: - scripts/tests/test_render_validation_html.py (17 passing, covers grade thresholds, category mapping, stats, score-bar rendering) --- .../2-plan-workflows/bmad-prd/SKILL.md | 140 ++++++------------ .../bmad-prd/assets/headless-schemas.md | 4 +- .../2-plan-workflows/bmad-prd/customize.toml | 17 ++- .../bmad-prd/references/headless.md | 39 +++-- .../bmad-prd/references/probing.md | 4 +- .../bmad-prd/references/validate.md | 35 +---- .../tests/test_render_validation_html.py | 130 ++++++++++++++++ 7 files changed, 224 insertions(+), 145 deletions(-) create mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/scripts/tests/test_render_validation_html.py diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md index 96c863cc8..81d66dbb0 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -4,137 +4,81 @@ description: Create, update, or validate a PRD. Use when the user wants help pro --- # BMad PRD -## Overview +Coach the user to a PRD they are proud of. Guide; do not do the thinking for them. -You are an expert PM facilitator. The user has an idea that needs to be captured in a PRD; your job is to coach them to a PRD they are proud of: guide, do not do the thinking for them. +## Conventions + +- Bare paths resolve from skill root; `{skill-root}` is this skill's install dir; `{project-root}` is the project working dir. +- `{workflow.}` resolves to fields in `customize.toml`'s `[workflow]` table (overrides win per BMad merge rules). +- `{doc_workspace}` is the bound run folder. `.decision-log.md` is the canonical ledger at its root; `addendum.md` is the optional technical-how sidecar. ## On Activation -1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, fall back to reading `{skill-root}/customize.toml` directly and proceed with built-in defaults. -2. Execute each entry in `{workflow.activation_steps_prepend}` in order. -3. Treat every entry in `{workflow.persistent_facts}` as foundational context. Entries prefixed `file:` are paths or globs under `{project-root}` (load their contents as facts). All others are facts verbatim. -4. Note `{workflow.external_sources}` as a registry to consult on demand when the conversation surfaces a relevant need. Do not query preemptively. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap. -5. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. -6. Detect mode and intent. If headless, read `references/headless.md` and follow it for the whole run. Otherwise greet `{user_name}` in `{communication_language}`. Detect intent from the user's first message and existing files: - - **Create**: no existing PRD resolves. - - **Update**: an existing `prd.md` is referenced or located. - - **Validate** (or *analyze*): user supplies an artifact and asks for feedback, or wants critique without changes. +1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults. +2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (entries prefixed `file:` are loaded). Note `{workflow.external_sources}` as an on-demand registry; never query preemptively. +3. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. Missing keys → neutral defaults; never block. +4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. Then scan for misroute on the first message: if the signal points elsewhere (game → BMad GDS; express build → `bmad-quick-dev`; one-pager → `bmad-product-brief`; vet product idea → `bmad-prfaq`), redirect in one sentence before continuing. +5. Detect intent: **Create** (no PRD), **Update** (existing PRD), **Validate** (critique only). If ambiguous, ask. +6. Run `{workflow.activation_steps_append}`. - If two intents could apply, confirm with one question. -7. Execute each entry in `{workflow.activation_steps_append}` in order. +## Intent Modes -## Session Posture +**Create.** Bind `{doc_workspace}` to `{workflow.prd_output_path}/{workflow.run_folder_pattern}/`. Write `prd.md` with YAML frontmatter (title, created, updated) and tell the user the path. Run `## Discovery`, then `## Finalize`. -- Plain and direct. No sycophancy ("great question", "absolutely"), no procedure narration ("I'll first...", "let me now..."), no length-nudge phrases ("concise", "brief"). -- Record as the user surfaces it. Decisions, assumptions, open questions land in `decision-log.md` or inline tags before the next turn. -- Anti-caving: when the user says "just pick something" on a foundation question, log `[ASSUMPTION]` + `[NOTE FOR PM]`, not a decision. When evidence is thin, say so; don't draft around the gap. When a validator surfaces a blocker, fix or log; don't rationalize. +**Update.** Reconcile the PRD with a change signal. Source-extract against PRD, addendum, `.decision-log.md`, and original inputs (extract, don't ingest). If `.decision-log.md` is missing, spawn a one-time bootstrap subagent to reverse-engineer a thin log from the PRD before continuing. Surface conflicts with prior decisions before applying. Then `## Finalize`. -## Intent Operating Modes - -**Create.** A PRD the user is proud of, drawn out through real conversation. Discovery first, drafting second. Bind `{doc_workspace}` to a fresh folder at `{workflow.output_dir}/{workflow.output_folder_name}/` and write `prd.md` there with YAML frontmatter (title, created, updated); tell the user the workspace path. Version and state transitions live in `decision-log.md`. When drafting is complete, proceed to `## Finalize`. - -**Update.** Reconcile an existing PRD with a change signal. Orient via source extractors (see `## Constraints` → Extract, don't ingest) against the PRD, addendum, `decision-log.md`, and original inputs, then run the `## Discovery` posture against the change signal. Surface conflicts with prior decisions before changing: read `decision-log.md`, identify decisions touching the same area as the change, and for each, check whether the change reverses it, contradicts a stated assumption, or removes a non-goal; if so, raise it to the user before applying. Once changes are applied, proceed to `## Finalize`. - -**Validate** (or *analyze*). Critique an existing PRD without changing it. Load `references/validate.md` and follow it. +**Validate** (or *analyze*). Critique without changing. Load `references/validate.md`. ## Discovery -For Create and Update intent, run Discovery in this order: **Brain dump → Four-dimension read → Right-skill check → Working mode.** Never skip ahead. +Order: **Brain dump → Four-dimension read → Working mode.** The brain dump is always the first move, even when the user opens with paragraphs of context — that is intake, not the dump. Read what exists; ask only what is missing. A simple "anything else?" surfaces what they almost forgot. -### Posture +Four dimensions: **Stakes** (rigor + section depth), **Audience** (tone + approval needs), **Existing inputs** (greenfield vs brownfield framing — brownfield means parts of the PRD reference, not relitigate), **Downstream depth** (standalone, or top of UX → architecture → epics → stories chain). -Coach, do not quiz. Push hardest on PRD Discipline risks: unexamined assumptions, capability-vs-implementation confusion, term drift, scope creep, ambiguity for downstream readers. +Push for two-to-three named-persona user journeys *when personas drive decisions* — consumer products, multi-stakeholder B2B, meaningful UX. Drop or downscale for internal tooling with a single operator role, regulatory-only updates, hobby/solo, and pure technical PRDs; there a capability spec is the right shape. -Push for two to three named-persona user journeys even when the user does not propose them. UJs are how teams discover persona gaps, scope ambiguity, and missed failure handling. Solo/hobby scope can drop to one or none. +Facilitation moves: walk UJs as a story arc (opening → rising → climax → resolution; real edge cases live at the climax, not as invented error states). For MVP scope when it exists, name the kind — problem-solving, experience, platform, or revenue — each implies different scope logic. Infer and confirm beats quiz ("I'm assuming X works like Y — right?" beats multiple choice). Load `references/probing.md` for the seven probe categories and the PRD/solution-design boundary. -Facilitation moves to keep handy. For User Journeys, walk the story shape: opening scene, rising action, climax (the moment value is delivered), resolution; real edge cases surface at the climax, not as invented error states. For MVP scope, ask which kind of MVP this is before listing in/out: problem-solving (proves the problem is solved), experience (proves the interaction model), platform (proves the base others build on), or revenue (proves willingness to pay); each implies different scope logic. For feature decisions, state the inference and invite correction rather than quizzing the user ("I'm assuming X works like Y, is that right?" beats "should X work like Y or Z?"). +**Working mode.** Once the read is complete, offer the choice in the user's language: -Load `references/probing.md` for the seven probing categories, critical-assumption scans, and the PRD / solution-design boundary; apply in Discovery and Update. +- **Fast path:** I batch remaining critical gaps, draft the full PRD, you review. +- **Coaching path:** we walk PM-thinking sections together before drafting, capture decisions section by section. -### Brain dump +The workspace persists, so they can stop and resume. Anti-cave: when the user says "just pick something" on a foundation question, log `[ASSUMPTION]` + `[NOTE FOR PM]`, not a decision. When evidence is thin, say so; do not draft around the gap. -**Always the first move for Create and Update intent, no exceptions.** Even when the user opens with a few sentences of context, that is intake — not the brain dump. Before any questions (especially multiple-choice), explicitly invite them to unload everything they have in mind: full picture, inputs, ideas, WHY. Read what exists first; ask only what is missing *after* the dump. A simple "anything else?" often surfaces what they almost forgot. - -Anti-pattern: treating the user's opening message as the full picture and jumping to assumptions, intake questions, or working-mode choices. The user may have a lot more to say; ask before assuming. The more they give us, the more we have to work with and the faster the process will be also for the user as we can help tighten and organize their own thinking and creativity as part of the PRD process as the user is the expert. - -### Four-dimension read - -Before drafting, read the situation across four dimensions; they determine the PRD's shape: - -- **Stakes.** Calibrates rigor, section depth, and which adapt-in clusters apply. -- **Audience.** Drives tone, evidence requirements, and approval sections. -- **Existing inputs.** Existing artifacts mean those parts of the PRD reference, not relitigate. When project-context, prior PRDs, or existing UX/architecture are present, this is brownfield; frame Discovery around what is new or changing. -- **Downstream depth.** Standalone spec, or top of a UX → architecture → epics → stories chain? Affects how much to encode vs. defer. - -### Right-skill check - -Sanity-check that PRD is the right tool before drafting: - -- **Games** → suggest BMad Game Dev Studio (GDS). -- **Small scope, wants a captured artifact** (small tweak to existing codebase, single doc to point at) → stay here, use the adapt-in Stories cluster for an all-inclusive document. -- **Express implementation** (build now, no planning chain, no captured artifact, small intent or story) → suggest skill `bmad-quick-dev` instead. - -### Working mode - -Working-mode choice comes *after* the brain dump and four-dimension read, never before. Once the situational read is complete, offer the user a choice before proceeding (one sentence per option): - -- **Express:** resolve any remaining critical gaps in a short batch, then draft the full PRD at once. -- **Facilitative:** work through the sections that require PM thinking before drafting. Capture all decisions in the log, section to section. Draft after the key sections are walked. The goal is that the user has authored the thinking, not just answered intake questions. - -In both modes, resolve decisions conversationally rather than silently deferring them into `[ASSUMPTION]` tags. Only use `[ASSUMPTION]` when the answer requires research or external input they cannot provide in the moment. +Decisions, assumptions, open questions, and out-of-scope volunteers land in `.decision-log.md` (or `addendum.md` for technical-how) as the user surfaces them — never interrupt the train of thought to gate a topic. ## PRD Discipline -### Artifact shape +**Shape.** Features grouped; FRs nested with globally numbered stable IDs. Cross-cutting NFRs in their own section; skip traceability matrices. Capabilities, not implementation — tech choices live in `addendum.md`. Load `{workflow.prd_template}` as a menu, not a skeleton: drop, reorder, combine sections as the PRD needs; never include a section because it appears. Counter-metrics named when Success Metrics exist. -- **Features grouped, FRs nested.** Features open with behavioral description; FRs nested and numbered globally for stable IDs. Cross-cutting NFRs in their own section; skip traceability matrices. -- **Capabilities, not implementation.** FRs describe what users or systems can do, not how. Tech choices go in addendum. -- **Right-size to purpose.** Load `{workflow.prd_template}` as the shape menu. Treat it as a menu, not a skeleton: drop, reorder, combine, or rename sections as the PRD needs; never include a section just because it appears. The essential spine is the floor, not the ceiling — hobby keeps it short, enterprise layers in clusters from the template's adapt-in menu. -- **Counter-metrics named.** When Success Metrics is present, name what NOT to optimize. +**Substance.** Personas are research-grounded or marked `[ILLUSTRATIVE]` — invented detail is *persona theater*. Two to four max, and they must drive decisions. Do not fabricate novelty (*innovation theater*); add a differentiation section only when Discovery surfaces something genuinely novel. Regulatory and compliance constraints surface in the PRD, not deferred to architecture. Inferences without direct user confirmation are tagged `[ASSUMPTION: ...]` inline and indexed at the end. -### Substance +**Scope honesty.** `[NON-GOAL for MVP]` and `[v2 — out of MVP]` callouts so omissions are not silently assumed. Never silently de-scope; propose phasing, never impose. `[NOTE FOR PM]` callouts at deferred decisions or unresolved tensions. -- **Personas, when used, are research-grounded or marked `[ILLUSTRATIVE]`.** Invented detail is *persona theater*: false specificity the team builds for. Personas must drive decisions; two to four max. -- **No innovation theater.** Don't fabricate novelty; add a differentiation section only when Discovery surfaced something genuinely novel. -- **Domain awareness.** Regulatory or compliance constraints surface in the PRD, not deferred to architecture. -- **Assumptions visible.** Inferences without direct user confirmation are tagged `[ASSUMPTION: ...]` inline and indexed at the end. - -### Honesty about scope - -- **Non-Goals explicit.** Pair with inline `[NON-GOAL for MVP]` and `[v2 — out of MVP]` callouts so omissions aren't silently assumed. -- **Never silently de-scope.** Nothing the user explicitly included drops without asking. Propose phasing; never impose it. -- **`[NOTE FOR PM]` callouts** at decision points the user deferred or left tension on. - -## Constraints - -- **File roles.** `decision-log.md`: every decision, change, and version transition. `addendum.md`: Technical-how detail to addendum immediately when the user volunteers it. -- **Continuity across sessions.** If a prior draft exists in `{workflow.output_dir}`, offer to resume; surface open items first. -- **Extract, don't ingest.** Never load source documents into the parent context wholesale. Delegate to subagents to extract what's relevant; the parent assembles from extracts. +**Extract, don't ingest.** Source documents go to subagents for extraction; the parent assembles from extracts. Never load source documents into the parent context wholesale. ## Reviewer Gate -Run during the Validate intent and at Finalize step 3. +Used by the Validate intent and at Finalize step 3. -**Menu.** Structural checklist validator (against `{workflow.validation_checklist}`) + each entry in `{finalize_reviewers}` (resolved on-demand from `customize.toml`) + any ad-hoc reviewers warranted by the artifact content (composed as plain-text entries on the fly). Stakes-calibrated: hobby/solo may run defaults quietly or skip; higher stakes get the explicit menu with all/subset/skip. +Assemble the menu: structural validator against `{workflow.validation_checklist_template}` + each entry in `{workflow.finalize_reviewers}` + any ad-hoc reviewers the artifact warrants. Stakes-calibrated — hobby/solo may run quietly or skip; higher stakes get the explicit all/subset/skip menu. -**Dispatch.** Spawn the selection as parallel subagents against `prd.md` (and `addendum.md` if present), by prefix: -- `skill:NAME` — invoke named skill. -- `file:PATH` — spawn an adversarial subagent giving the agent the file path to use as review lens. -- `text` — follow the instructions use directly as the subagent's prompt. +Dispatch entries as parallel subagents against `prd.md` (and `addendum.md` if present) using the standard prefix convention (`skill:` / `file:` / plain text). Each writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary (verdict, top 2-5 findings, file path) — the parent never holds full review text. If subagents are unavailable, run sequentially: write the file *before* anything else, then flush the review from working context. -**Subagent contract.** Each reviewer writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary (verdict, top 2-5 findings succinct, file path). The parent never holds full review text unless tool does not support subagents. Under Validate intent, the structural validator additionally runs the rendering pipeline in `references/validate.md`. +Surface findings tiered, never dumped. Lead with a one-sentence gate verdict, then walk critical + high findings; medium/low roll into a single tail ("plus N more in {file}"). Read the full `review-{slug}.md` only when the user drills into a specific finding. Per finding: autofix, discuss, defer to open items, or ignore. -**Walk-through.** Present the findings in an organized facilitative fashion. Per finding user can choose to: autofix, discuss, defer to open items, or ignore. +Under Validate intent, the structural validator additionally runs the rendering pipeline in `references/validate.md`. ## Finalize -At entry, name the sequence for the user in one sentence: walk the decision log, reconcile inputs, run the reviewer pass, resolve open items, then polish over the final content. Polish goes last so it does not have to redo work after reviewer fixes. +Tell the user the sequence in one sentence, then walk it. Polish goes last so it does not redo work after reviewer fixes. -1. Decision log audit: walk `decision-log.md` with the user; each entry captured in PRD, in addendum, or set aside. -2. Input reconciliation: subagent per user-supplied input against `prd.md` + `addendum.md`; surface gaps, especially qualitative ideas (tone, voice, feel) the FR structure silently drops. Must happen before polish. -3. Reviewer pass: run the `## Reviewer Gate` against `prd.md`. Resolve before polish. -4. Triage all Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts. A phase-blocker is an open item that would make the PRD unsafe for the next phase of work (UX, architecture, epics); a non-blocker is deferrable to a later cycle with an owner and revisit condition. Surface only phase-blockers one at a time; resolve before calling the PRD ready. Log deferred items to `decision-log.md`. If phase-blocker count is high, flag it. -5. Polish: apply `{workflow.doc_standards}` to `prd.md` and `addendum.md` via parallel subagents. -6. External handoffs: execute `{workflow.external_handoffs}` entries; surface returned URLs/IDs. Skip and flag unavailable tools. -7. Record finalization to `decision-log.md`. Share all artifact paths. Invoke `bmad-help` to share possible steps. +1. **Decision log audit.** Walk `.decision-log.md` with the user; each entry captured in PRD, in addendum, or set aside. +2. **Input reconciliation.** Subagent per user-supplied input against `prd.md` + `addendum.md`. Each writes its extract to `{doc_workspace}/reconcile-{slug}.md` and returns ONLY a compact summary (input name, gaps 2-5, file path). Surface gaps — especially qualitative ideas (tone, voice, feel) the FR structure silently drops. Must happen before polish. +3. **Reviewer pass.** Run `## Reviewer Gate`. Resolve before polish. +4. **Triage open items.** All Open Questions, `[ASSUMPTION]` tags, `[NOTE FOR PM]` callouts. Phase-blockers (would make the PRD unsafe for UX/architecture/epics) surfaced one at a time and resolved; non-blockers deferred with owner + revisit condition logged to `.decision-log.md`. If phase-blocker count is high, flag it. +5. **Polish.** Apply `{workflow.doc_standards}` to `prd.md` and `addendum.md` in declared order (structural passes before prose — prose should not polish soon-to-be-cut text). Parallelize across documents, sequential within. +6. **External handoffs.** Execute `{workflow.external_handoffs}`; surface returned URLs/IDs. Skip and flag unavailable tools. +7. **Close.** Record finalization to `.decision-log.md`. Share artifact paths. Common next: `bmad-create-ux-design`, `bmad-create-architecture`, `bmad-create-epics-and-stories`; invoke `bmad-help` for authoritative routing. 8. Run `{workflow.on_complete}` if non-empty. diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/headless-schemas.md b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/headless-schemas.md index c70a02666..82c53e6f9 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/headless-schemas.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/headless-schemas.md @@ -18,7 +18,7 @@ Every headless run ends with one of these payloads. Omit keys for artifacts not "intent": "create", "prd": "{doc_workspace}/prd.md", "addendum": "{doc_workspace}/addendum.md", - "decision_log": "{doc_workspace}/decision-log.md", + "decision_log": "{doc_workspace}/.decision-log.md", "open_questions": [], "assumptions": [], "external_handoffs": [ @@ -34,7 +34,7 @@ Every headless run ends with one of these payloads. Omit keys for artifacts not "status": "complete", "intent": "update", "prd": "{doc_workspace}/prd.md", - "decision_log": "{doc_workspace}/decision-log.md", + "decision_log": "{doc_workspace}/.decision-log.md", "changes_summary": "1-3 sentences describing what changed and why", "conflicts_with_prior_decisions": [], "open_questions": [], diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml b/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml index 6cda93020..a19ba87d2 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml @@ -47,7 +47,7 @@ prd_template = "assets/prd-template.md" # A subagent walks the checklist against prd.md and returns structured findings. # Override the path in team/user TOML to enforce an org-specific checklist # (regulated-industry compliance, investor-pitch standards, etc.). -validation_checklist = "assets/prd-validation-checklist.md" +validation_checklist_template = "assets/prd-validation-checklist.md" # HTML template used to render validation findings into a styled, scannable # report. The renderer (scripts/render-validation-html.py) substitutes @@ -57,9 +57,10 @@ validation_checklist = "assets/prd-validation-checklist.md" validation_report_template = "assets/validation-report-template.html" # Run folder location. The PRD, optional addendum, decision log, and optional -# validation report all land inside `{output_dir}/{output_folder_name}/`. -output_dir = "{planning_artifacts}/prds" -output_folder_name = "prd-{project_name}-{date}" +# validation report all land inside `{prd_output_path}/{run_folder_pattern}/`. +# Resume-check scans `{prd_output_path}` for prior unfinished runs. +prd_output_path = "{planning_artifacts}/prds" +run_folder_pattern = "prd-{project_name}-{date}" # Document standards applied to human-consumed docs at finalize. Each entry is # a `skill:`, `file:`, or plain-text directive; the parent LLM applies the @@ -90,6 +91,11 @@ doc_standards = [ # tool needs. If a named MCP tool is unavailable at runtime, the LLM falls # back to standard behavior and notes the gap. Empty by default. # +# Lifecycle note: distinct from persistent_facts. persistent_facts are loaded +# once at activation and kept in mind for the whole run; external_sources are +# a registry consulted on demand and only when the conversation surfaces a +# matching need. +# # Examples (set in team/user override TOML): # "When researching internal product context, consult corp:kb_search (database='product-docs') before web search." # "For competitive landscape during Discovery, query corp:competitive_db with category={project_name}." @@ -106,6 +112,9 @@ external_sources = [] # status; local files always exist regardless. Fires automatically — users # can opt out in their prompt for a specific run. Empty by default. # +# Lifecycle note: distinct from persistent_facts and external_sources. +# Fired once at Finalize step 6, never during Discovery or drafting. +# # Examples (set in team/user override TOML): # "After finalize, upload prd.md and addendum.md to Confluence via corp:confluence_upload (space_key='PROD', parent_page='PRDs', label='prd', author={user_name})." # "Mirror the PRD to Notion via notion:create_page (database_id='abc123', title='PRD: '+{project_name})." diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/references/headless.md b/src/bmm-skills/2-plan-workflows/bmad-prd/references/headless.md index 761730efc..2d4c7588d 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/references/headless.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/headless.md @@ -2,23 +2,38 @@ Load this file when bmad-prd is invoked headless (no interactive user). Follow it for the whole run. +## Detection + +Headless mode is in effect when any of the following is true: + +- the invoking caller sets a `headless: true` flag (or equivalent argument the harness exposes), +- the invocation is from another skill or a non-interactive runner (no TTY, no user message stream), +- `{workflow.activation_steps_prepend}` includes an entry that explicitly declares headless, +- the first message comes from an automation context that pre-supplies all inputs and asks for an artifact path back. + +When ambiguous, default to interactive. + +## Inputs the caller is expected to provide + +The caller passes inputs in their first message (free-form structured payload; no fixed schema, but every field below should be present when applicable): + +- `intent` — `"create"`, `"update"`, or `"validate"`. If absent, infer from the artifact set. +- For **Create**: a brief or product spec the LLM works from (plain text, file path, or URL), plus any persona/scope notes; `doc_workspace` if a specific run folder is required (otherwise the workflow binds the default). +- For **Update**: the existing `prd.md` path (or a workspace path that contains one), and a change signal (the request: what to change and why). +- For **Validate**: the existing `prd.md` path (or workspace path), and optionally a checklist override path. Workspace defaults to the PRD's containing directory. + +Anything the caller does not provide is either inferred from inputs/workspace or recorded as `assumptions[]` / `open_questions[]` in the JSON status. Do not invent persona detail, success metrics, or scope decisions to fill gaps — record them. + ## General -Do not ask. Complete the intent using what is provided, what exists in `{doc_workspace}`, or what you can discover yourself. If intent remains ambiguous after inference, halt with a `blocked` JSON status and a `reason` field — do not prompt. Do not greet. +Do not ask. Complete the intent using what is provided, what exists in `{doc_workspace}`, or what you can discover yourself. If intent remains ambiguous after inference, halt with `status: "blocked"` and a `reason` field — do not prompt. Do not greet. -End with a JSON response listing status, intent, and artifact paths. The `intent` field must match the detected intent: `"create"`, `"update"`, or `"validate"`. Omit keys for artifacts not produced. Full schemas with examples for each intent are in `assets/headless-schemas.md`. Minimal shape: +Populate `assumptions[]` with every value you inferred without direct caller confirmation; populate `open_questions[]` with every gap that needs a human decision. Use `status: "partial"` when the artifact was produced but `open_questions[]` is non-empty or critical inputs were inferred (Create with no brief; Update with a vague signal acted on best-effort; Validate that could not load the checklist). `complete` = stands on its own; `partial` = caller should review before downstream use; `blocked` = no artifact produced. -```json -{ - "status": "complete", - "intent": "validate", - "validation_report": "{doc_workspace}/validation-report.md", - "offer_to_update": true -} -``` +End with the JSON response (full schemas with examples in `assets/headless-schemas.md`). The `intent` field must match the detected intent. Omit keys for artifacts not produced. ## Mode-specific overrides -**Update.** Log the reversal to `decision-log.md`, then apply. Halt `blocked` if intent is ambiguous. +**Update.** Apply the change, log to `.decision-log.md` with rationale, and surface any conflict-with-prior-decision in `conflicts_with_prior_decisions[]` in the JSON status. Halt `blocked` if intent is ambiguous. -**Validate.** Always write `validation-report.md` to `{doc_workspace}` regardless of finding count. Always include `"offer_to_update": true` in the JSON status block. +**Validate.** Always write `validation-report.md` to `{doc_workspace}` regardless of finding count. Always include `"offer_to_update": true` in the JSON status. Run the renderer without `--open`. diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md b/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md index 03b01cc5b..a235b28be 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md @@ -9,10 +9,10 @@ One probe per turn. When multiple gaps surface, pick the most load-bearing; reco | Trigger | Probe | Where it lands | |---|---|---| | Vague outcome ("better", "faster", "love it") | "What does it look like when it's working? How would you know?" | §7 Success Metrics, or Open Question | -| Evidence conflict (implied behavior change contradicts existing PRD/code/decision) | "Current behavior is X per [source]. Is the change to Y deliberate?" | `decision-log.md`; `[NOTE FOR PM]` in affected feature | +| Evidence conflict (implied behavior change contradicts existing PRD/code/decision) | "Current behavior is X per [source]. Is the change to Y deliberate?" | `.decision-log.md`; `[NOTE FOR PM]` in affected feature | | Scope ambiguity ("all users", "the checkout flow") | "Does this apply to X? Is Y in or out?" | §5 Non-Goals or inline `[NON-GOAL]` | | Missing failure UX (happy path only) | "What does the user see when X fails? Acceptable, or needs handling?" | Feature/FR; Open Question if undecided | -| Competing commitments (two requirements in tension) | "When A and B conflict, which wins?" | `decision-log.md` + counter-metric in §7 | +| Competing commitments (two requirements in tension) | "When A and B conflict, which wins?" | `.decision-log.md` + counter-metric in §7 | | Data availability (SM depends on data not verified to exist) | "Does the data exist today in measurable form? Baseline?" | SM definition or `[ASSUMPTION]` | | Design readiness (UI implied without design) | "Reviewed design exists, or Open Question?" | Open Question; ref `bmad-create-ux-design` | diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/references/validate.md b/src/bmm-skills/2-plan-workflows/bmad-prd/references/validate.md index fe1e2380f..b178fe79b 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/references/validate.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/validate.md @@ -1,28 +1,24 @@ # Validate -The full Validate intent playbook. Also covers the structural-validator rendering pipeline used during mid-session report requests. - -Critique an existing PRD without changing it. Standalone; does NOT enter `## Finalize`. +The Validate intent playbook. Standalone — this intent critiques an existing PRD without changing it and ends after the user has seen the report; it does not run Finalize. The structural-validator rendering pipeline below is also reused for mid-session report requests during Create/Update. ## Orient -Source-extract against `decision-log.md`, any original inputs, and the PRD/addendum themselves. Delegate to subagents per `## Constraints` → Extract, don't ingest; the parent assembles from extracts. +Source-extract against `.decision-log.md`, any original inputs, and the PRD/addendum themselves. Delegate to subagents per PRD Discipline → "Extract, don't ingest" (in SKILL.md); the parent assembles from extracts. ## Run the Reviewer Gate -Run the `## Reviewer Gate` (in SKILL.md) against `prd.md` (and `addendum.md` if present). The gate handles menu assembly, parallel dispatch, the subagent contract, and the section-by-section walk-through. - -The structural checklist validator is one entry in the gate menu; under Validate intent it additionally runs the rendering pipeline below. The Finalize discipline pass during Create/Update does NOT render a report — its findings stay in-conversation. +Run the Reviewer Gate (see SKILL.md) against `prd.md` (and `addendum.md` if present). The structural checklist validator is one entry in the gate menu; under Validate intent it additionally runs the rendering pipeline below. The Finalize discipline pass during Create/Update does NOT render a report — its findings stay in-conversation. ## Structural validator pipeline -The structural validator subagent walks `{workflow.validation_checklist}` against `prd.md` (and `addendum.md` if present) and writes findings to `{doc_workspace}/validation-findings.json`: +The structural validator subagent walks `{workflow.validation_checklist_template}` against `prd.md` (and `addendum.md` if present) and writes findings to `{doc_workspace}/validation-findings.json`: ```json { "prd_name": "Example Product", "prd_path": "{doc_workspace}/prd.md", - "checklist_path": "{workflow.validation_checklist}", + "checklist_path": "{workflow.validation_checklist_template}", "timestamp": "2026-01-15T09:14:00", "overall_synthesis": "2-3 sentences of judgment about the PRD's overall state — what holds up, what's at risk. Written by the subagent, not the parent.", "findings": [ @@ -40,21 +36,10 @@ The structural validator subagent walks `{workflow.validation_checklist}` agains } ``` -Per-finding fields: - -- `id` (required) — checklist item ID (e.g., `Q-1`, `D-2`, `STK-1`, or org-custom prefixes). -- `category` (optional) — explicit category name; if omitted, the renderer maps from the ID prefix. -- `title` (optional but recommended) — the checklist item's short name. -- `status` — `pass` | `warn` | `fail` | `n/a`. -- `severity` — `low` | `medium` | `high` | `critical`. -- `location` (optional) — section/line/range in the PRD where the finding lives. Cite specifics, never abstract criticism. -- `note` (optional) — the finding itself, in one or two sentences. -- `suggested_fix` (optional) — concrete next action. +Required per-finding fields: `id`, `status` (`pass` | `warn` | `fail` | `n/a`), `severity` (`low` | `medium` | `high` | `critical`). Optional: `category` (renderer derives from ID prefix if omitted), `title`, `location` (cite specifics, never abstract criticism), `note`, `suggested_fix`. ### Render -After the subagent writes findings: - ```bash python3 {skill-root}/scripts/render-validation-html.py \ --findings {doc_workspace}/validation-findings.json \ @@ -63,12 +48,8 @@ python3 {skill-root}/scripts/render-validation-html.py \ --open ``` -Include `--open` for interactive runs (auto-opens in default browser). Omit `--open` in headless runs. - -The script writes two artifacts side-by-side: the HTML report at `--output`, and a markdown companion at the same path with `.md` extension (e.g. `validation-report.md`). Both are always produced when the script runs. It computes pass/warn/fail/na counts, derives a grade (Excellent / Good / Fair / Poor) from critical-fail and total-fail counts, renders an inline SVG score bar in the HTML, groups findings by category, and returns a one-line JSON summary on stdout: `{"output": "...", "markdown": "...", "grade": "...", "stats": {...}}`. - -Re-running validation overwrites existing report files in place. Markdown form is what Update mode reads when rolling findings into a revision. +Use `--open` interactive, omit headless. Writes HTML + markdown twin + JSON summary on stdout; re-running overwrites in place. Update mode reads the markdown form when rolling findings into a revision. ## Close -Surface all artifact paths and summaries to the user. The Reviewer Gate's walk-through covers section-by-section review of findings; the rendered HTML/markdown report is the persistent artifact. Always offer to roll findings into an Update; Validate itself does not change `prd.md`. +Surface artifact paths; the rendered HTML/markdown is the persistent artifact. Always offer to roll findings into an Update. diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/scripts/tests/test_render_validation_html.py b/src/bmm-skills/2-plan-workflows/bmad-prd/scripts/tests/test_render_validation_html.py new file mode 100644 index 000000000..38c810822 --- /dev/null +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/scripts/tests/test_render_validation_html.py @@ -0,0 +1,130 @@ +#!/usr/bin/env python3 +# /// script +# requires-python = ">=3.10" +# /// +"""Unit tests for render-validation-html.py. + +Run from the skill root: + python3 -m unittest scripts/tests/test_render_validation_html.py +""" + +import importlib.util +import sys +import unittest +from pathlib import Path + +# Load the sibling module via importlib because its filename has a hyphen. +SCRIPT_PATH = Path(__file__).resolve().parents[1] / "render-validation-html.py" +spec = importlib.util.spec_from_file_location("render_validation_html", SCRIPT_PATH) +rvh = importlib.util.module_from_spec(spec) +sys.modules["render_validation_html"] = rvh +spec.loader.exec_module(rvh) + + +class CategoryForTests(unittest.TestCase): + def test_explicit_category_wins(self): + self.assertEqual(rvh.category_for({"id": "Q-1", "category": "Custom"}), "Custom") + + def test_known_prefixes_map(self): + self.assertEqual(rvh.category_for({"id": "Q-3"}), "Quality") + self.assertEqual(rvh.category_for({"id": "D-2"}), "Discipline") + self.assertEqual(rvh.category_for({"id": "S-1"}), "Structural integrity") + self.assertEqual(rvh.category_for({"id": "STK-1"}), "Stakes-gated") + self.assertEqual(rvh.category_for({"id": "M-9"}), "Mechanical") + + def test_unknown_prefix_falls_through(self): + self.assertEqual(rvh.category_for({"id": "X-1"}), "X") + + def test_id_without_hyphen_used_directly(self): + self.assertEqual(rvh.category_for({"id": "FOO"}), "FOO") + + def test_empty_id_yields_other(self): + self.assertEqual(rvh.category_for({}), "Other") + + +class GradeThresholdTests(unittest.TestCase): + def _stats(self, **kw): + base = {"total": 0, "passed": 0, "warned": 0, "failed": 0, "na": 0, + "failed_critical": 0, "failed_high": 0} + base.update(kw) + return base + + def test_any_critical_fail_is_poor(self): + grade, cls = rvh.grade_from(self._stats(failed=1, failed_critical=1)) + self.assertEqual(grade, "Poor") + self.assertEqual(cls, "grade-poor") + + def test_single_high_fail_is_fair(self): + grade, _ = rvh.grade_from(self._stats(failed=1, failed_high=1)) + self.assertEqual(grade, "Fair") + + def test_four_failures_is_fair_even_without_high(self): + grade, _ = rvh.grade_from(self._stats(failed=4)) + self.assertEqual(grade, "Fair") + + def test_three_failures_no_high_is_good(self): + grade, _ = rvh.grade_from(self._stats(failed=3)) + self.assertEqual(grade, "Good") + + def test_many_warnings_drops_to_good(self): + grade, _ = rvh.grade_from(self._stats(warned=3)) + self.assertEqual(grade, "Good") + + def test_clean_run_is_excellent(self): + grade, cls = rvh.grade_from(self._stats(passed=10)) + self.assertEqual(grade, "Excellent") + self.assertEqual(cls, "grade-excellent") + + def test_two_warnings_still_excellent(self): + grade, _ = rvh.grade_from(self._stats(passed=5, warned=2)) + self.assertEqual(grade, "Excellent") + + +class ComputeStatsTests(unittest.TestCase): + def test_counts_by_status_and_severity(self): + findings = [ + {"status": "pass"}, + {"status": "warn"}, + {"status": "fail", "severity": "critical"}, + {"status": "fail", "severity": "high"}, + {"status": "fail", "severity": "low"}, + {"status": "n/a"}, + ] + stats = rvh.compute_stats(findings) + self.assertEqual(stats["total"], 6) + self.assertEqual(stats["passed"], 1) + self.assertEqual(stats["warned"], 1) + self.assertEqual(stats["failed"], 3) + self.assertEqual(stats["na"], 1) + self.assertEqual(stats["failed_critical"], 1) + self.assertEqual(stats["failed_high"], 1) + + def test_missing_status_treated_as_na(self): + stats = rvh.compute_stats([{}, {}]) + self.assertEqual(stats["na"], 2) + + def test_empty_findings(self): + stats = rvh.compute_stats([]) + self.assertEqual(stats["total"], 0) + + +class ScoreBarTests(unittest.TestCase): + def test_renders_svg_with_four_segments(self): + stats = {"total": 4, "passed": 1, "warned": 1, "failed": 1, "na": 1} + svg = rvh.render_score_bar(stats, width=400, height=20) + self.assertIn(" Date: Fri, 15 May 2026 21:44:53 -0500 Subject: [PATCH 08/10] refactor(bmad-prd): replace mechanical checklist+renderer with quality rubric and LLM-synthesized report MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The structural checklist + Python renderer produced mechanical pass/warn/fail reports that didn't speak to actual PRD quality, and additional reviewers (adversarial) wrote separate review-*.md files that never made it into the HTML. Replaces that pipeline with: - A judgment rubric across seven PRD-quality dimensions (decision-readiness, substance over theater, strategic coherence, done-ness clarity, scope honesty, downstream usability, shape fit) that adapts to stakes and PRD shape. Rubric walker writes review-rubric.md with per-dimension verdicts. - HTML skeleton with TEMPLATE_* placeholders the synthesis pass fills directly — no substitution engine, no Python. - Synthesis pipeline in references/validate.md: parent reads every review-*.md, fills the skeleton, writes validation-report.html plus markdown twin, opens via webbrowser. Folds every reviewer's findings into one report; grade derives from rubric verdicts and severity counts. - Drops scripts/render-validation-html.py and scripts/tests/ entirely. - finalize_reviewers defaults to empty (adversarial removed from defaults — too brutal and frequently wrong against PRDs; teams can append in override TOML). - Headless mode now writes both HTML and markdown; skips browser-open. --- .../2-plan-workflows/bmad-prd/SKILL.md | 8 +- .../assets/prd-validation-checklist.md | 150 +++++++-- .../assets/validation-report-template.html | 253 +++++++++++---- .../2-plan-workflows/bmad-prd/customize.toml | 26 +- .../bmad-prd/references/headless.md | 2 +- .../bmad-prd/references/validate.md | 116 ++++--- .../scripts/render-validation-html.py | 290 ------------------ .../tests/test_render_validation_html.py | 130 -------- 8 files changed, 418 insertions(+), 557 deletions(-) delete mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/scripts/render-validation-html.py delete mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/scripts/tests/test_render_validation_html.py diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md index 81d66dbb0..043c32bf9 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -1,6 +1,6 @@ --- name: bmad-prd -description: Create, update, or validate a PRD. Use when the user wants help producing, editing, validating, or analyzing a PRD. +description: Create, update, or validate a PRD. Use when the user wants help producing, editing, or validating a PRD. --- # BMad PRD @@ -62,13 +62,13 @@ Decisions, assumptions, open questions, and out-of-scope volunteers land in `.de Used by the Validate intent and at Finalize step 3. -Assemble the menu: structural validator against `{workflow.validation_checklist_template}` + each entry in `{workflow.finalize_reviewers}` + any ad-hoc reviewers the artifact warrants. Stakes-calibrated — hobby/solo may run quietly or skip; higher stakes get the explicit all/subset/skip menu. +Assemble the menu: rubric walker against `{workflow.validation_checklist_template}` (the PRD quality rubric) + each entry in `{workflow.finalize_reviewers}` + any ad-hoc reviewers the artifact warrants. Stakes-calibrated — hobby/solo may run quietly or skip; higher stakes get the explicit all/subset/skip menu. -Dispatch entries as parallel subagents against `prd.md` (and `addendum.md` if present) using the standard prefix convention (`skill:` / `file:` / plain text). Each writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary (verdict, top 2-5 findings, file path) — the parent never holds full review text. If subagents are unavailable, run sequentially: write the file *before* anything else, then flush the review from working context. +Dispatch entries as parallel subagents against `prd.md` (and `addendum.md` if present) using the standard prefix convention (`skill:` / `file:` / plain text). Each writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary (verdict, top 2-5 findings, file path) — the parent never holds full review text. The rubric walker uses the prompt and output format in `references/validate.md`. If subagents are unavailable, run sequentially: write the file *before* anything else, then flush the review from working context. Surface findings tiered, never dumped. Lead with a one-sentence gate verdict, then walk critical + high findings; medium/low roll into a single tail ("plus N more in {file}"). Read the full `review-{slug}.md` only when the user drills into a specific finding. Per finding: autofix, discuss, defer to open items, or ignore. -Under Validate intent, the structural validator additionally runs the rendering pipeline in `references/validate.md`. +Under Validate intent, the parent additionally runs the synthesis pipeline in `references/validate.md` — folding every selected reviewer's output into a single HTML + markdown report and opening the HTML. ## Finalize diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-validation-checklist.md b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-validation-checklist.md index 2f1429b02..665b1835f 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-validation-checklist.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-validation-checklist.md @@ -1,33 +1,135 @@ -# PRD Validation Checklist +# PRD Quality Rubric -Loaded by the PRD validator subagent. For each item, return `{id, status: pass|fail|warn|n/a, severity: low|medium|high|critical, location, note}`. Skip items not applicable to the agreed stakes. Cite specific PRD locations — never abstract criticism. +A judgment rubric for the validator subagent. Walk the PRD with these dimensions in mind and write substantive findings — not box-ticking. The goal is a review that tells the user whether this PRD is *good*, not whether it has the right section headers. -## Quality +Most PRDs do not need every dimension scrutinized equally. Calibrate to the agreed stakes, the PRD's shape (consumer product, internal tool, regulatory update, technical capability spec), and what the PRD itself is trying to do. Be specific — cite locations, quote phrases, name what's missing. Abstract criticism is failure of nerve. -- **Q-1. Information density.** Sentences carry weight. Flag filler, hedging, and conversational padding. -- **Q-2. Measurability.** Where measurement matters, FRs and Success Metrics are measurable; subjective adjectives flagged. Counter-metrics named when Success Metrics exist. -- **Q-3. Traceability.** Every FR includes `Realizes UJ-X` referencing a UJ in §2.4. Every SM includes `Validates FR-X` referencing one or more FRs. Cross-references resolve. -- **Q-4. Vision and JTBDs concrete.** Vision is specific and stands alone — not a generic feature list. JTBDs are audience-grounded, not abstract. -- **Q-5. Non-Goals explicit.** A Non-Goals section is present where it would do real work; inline `[NON-GOAL]` and `[v2]` callouts where omissions would otherwise be silently assumed. -- **Q-6. Dual-audience and self-contained.** Each section makes sense pulled out alone (cross-references via Glossary terms, not "see above"); the PRD is readable by humans and structured cleanly for downstream source-extraction by UX, architecture, and story-creation workflows. -- **Q-7. FR testability.** Every FR has at least one testable consequence (verifiable condition with measurable outcome). Flag hand-waves like "system handles X gracefully" or "reasonable performance." +## How to use this rubric -## Discipline +1. Read the full PRD (and addendum.md if present) before writing anything. +2. For each of the seven dimensions below, form a judgment — *strong / adequate / thin / broken* — backed by specifics from the PRD. +3. Write findings only where they add information. A `strong` dimension may need no findings; a `broken` one needs concrete, fixable ones. +4. Severity ranks impact on the PRD's usefulness, not how easy the fix is. A vague Vision statement is *critical* even though it's a one-paragraph fix; a glossary drift might be *low* even though it appears in many places. +5. The overall verdict is your synthesis — 2–3 sentences that name what holds up and what's at risk. Earn it with the dimension judgments. -- **D-1. Capabilities, not implementation.** FRs describe what users/systems can do, not how. Flag technology names, library choices, architecture decisions. -- **D-2. Input fidelity.** Requirements from input documents (brief, research, prior PRD) are still in scope or explicitly handled via Non-Goals or `[ASSUMPTION]`. -- **D-3. Personas grounded.** If personas exist, they are research-grounded or marked `[ILLUSTRATIVE]`. Each persona drives at least one decision. -- **D-4. No innovation theater.** Novelty claims are real, not invented. +## Output format -## Structural integrity +Write findings to `{doc_workspace}/review-rubric.md`: -- **S-1. Glossary integrity.** Every domain noun is defined in the Glossary and used identically throughout — including in FR descriptions, consequences, UJ flows, and SM definitions. Flag drift (case, plural, synonyms) and candidate missing-term entries. -- **S-2. ID continuity.** FR / UJ / SM / Story IDs are contiguous, unique, and cross-references resolve. -- **S-3. Assumptions Index.** Every inline `[ASSUMPTION: ...]` appears in the Assumptions Index and vice versa. -- **S-4. Open-items density.** Count Open Questions + `[ASSUMPTION]` + `[NOTE FOR PM]`. Red flag if density is high relative to the agreed stakes. -- **S-5. UJ persona linkage.** Every UJ names a persona from §2 by exact label. Flag floating UJs that don't tie to a defined persona. +```markdown +# PRD Quality Review — {prd_name} -## Stakes-gated +## Overall verdict +[2–3 sentences. What holds up, what's at risk. Earned by the dimension judgments below.] -- **STK-1. Required sections.** The PRD includes the sections the agreed stakes and product type warrant. -- **STK-2. UJ density.** For non-hobby/non-solo scope, at least two named-persona UJs present in §2.4. Hobby/solo scope is exempt. +## Decision-readiness — [strong | adequate | thin | broken] +[1–3 paragraphs of judgment with specific PRD locations.] + +### Findings +- **[critical|high|medium|low]** [Title] (§ location) — [Note]. *Fix:* [suggested fix]. + +## Substance over theater — [verdict] +... + +(repeat for each dimension) + +## Mechanical notes +[Glossary drift, ID continuity, broken cross-refs, Assumptions Index roundtrip. Lighter weight — these matter for downstream but don't drive the overall verdict.] +``` + +## The seven dimensions + +### 1. Decision-readiness + +Can a decision-maker act on this PRD? Are the trade-offs surfaced honestly, or has the PRD smoothed everything to neutral? Would someone pushing back find their objection acknowledged or dodged? + +Look for: +- Decisions that are stated as decisions, not buried as "considerations." +- Trade-offs named with what was given up, not just what was chosen. +- Open Questions that are actually open — not rhetorical questions with an answer in the next sentence. +- `[NOTE FOR PM]` callouts at real tensions, not at safe checkpoints. + +Red flag: a PRD where every choice "balances" everything, every NFR is "important," every persona "values" the product. + +### 2. Substance over theater + +Is the content earned, or is it furniture? Distinguish: + +- **Persona theater** — invented persona detail unmarked as `[ILLUSTRATIVE]`. Personas that don't drive a single decision in the PRD. More than four personas. Personas whose only function is to make the PRD look thorough. +- **Innovation theater** — claimed novelty that isn't novel. Differentiation sections written because the template had one, not because Discovery surfaced something. +- **NFR theater** — copied boilerplate ("system must be scalable / secure / reliable") without product-specific thresholds. +- **Vision theater** — a Vision statement that could swap into any PRD in this category without change. + +Flag what reads like furniture, even if it's well-written furniture. + +### 3. Strategic coherence + +Does the PRD have a thesis? Do the features serve a unified arc, or is it a list of capabilities someone wanted? + +Look for: +- A stated thesis the PRD bets on (problem framing, user insight, market move). +- Feature prioritization that follows from the thesis — not from "what's easy first." +- Success Metrics that validate the thesis, not metrics that just measure activity (DAU/MAU when the thesis is about engagement quality is a tell). +- Counter-metrics named when SMs exist. +- Coherent MVP scope kind — problem-solving, experience, platform, or revenue — with scope logic that matches. + +Red flag: a PRD that reads as a backlog with section headings. + +### 4. Done-ness clarity + +Would an engineer reading this PRD know what "done" looks like for each FR? + +Look for: +- FRs with at least one testable consequence per FR — verifiable condition, measurable outcome. +- "System handles X gracefully," "reasonable performance," "user-friendly" — flag every one. +- Acceptance criteria implied or explicit. Sometimes the FR's consequences carry this; sometimes the PRD genuinely needs an Acceptance section. +- For non-functional sections (UX, performance, security): bounds, not adjectives. + +This is the dimension downstream story creation will lean on hardest. Be unforgiving here. + +### 5. Scope honesty + +Are omissions explicit, or is the reader meant to infer them? + +Look for: +- A Non-Goals section where it would do real work — and `[NON-GOAL for MVP]` / `[v2 — out of MVP]` callouts where omissions could be silently assumed. +- `[ASSUMPTION: …]` tags on inferences the user didn't directly confirm, indexed at the end. +- `[NOTE FOR PM]` callouts at deferred decisions and unresolved tensions. +- De-scoping proposed honestly, not done silently. + +Open-items density: count Open Questions + `[ASSUMPTION]` + `[NOTE FOR PM]` callouts relative to stakes. High counts on a low-stakes PRD is fine; high counts on a green-light-to-build PRD is a blocker. + +### 6. Downstream usability + +If this PRD feeds UX, architecture, or story creation, can those workflows source-extract from it cleanly? + +Look for: +- Glossary present; every domain noun used identically across FRs, UJs, SM definitions. +- FR / UJ / SM IDs contiguous, unique, and cross-references that resolve. +- Each section makes sense pulled out alone — cross-references via Glossary terms, not "see above." +- UJs each name a persona from §2 by exact label; no floating UJs. + +For standalone PRDs (no downstream), this dimension matters less — say so. + +### 7. Shape fit + +Has the PRD been forced into a shape that doesn't match the product? + +- Consumer product / multi-stakeholder B2B / meaningful UX → UJs and personas are load-bearing. +- Internal tool, single-operator role → capability spec shape; UJs may be overhead; SMs may be operational rather than user-facing. +- Regulatory or compliance update → constraint traceability is non-negotiable; UJs may be irrelevant. +- Hobby / solo → rigor light, substance bar still applies. +- Brownfield → existing-code references must be accurate; new UJs and existing UJs must be distinguished. +- Chain-top (feeds UX → architecture → stories) → downstream usability matters more; standalone PRDs can be lighter on traceability. + +Flag PRDs that are over-formalized (UJ density for a single-operator tool) or under-formalized (consumer product with no personas or UJs). + +## Mechanical notes + +Cover these as a tail section, not a primary dimension. They matter for downstream but don't drive the verdict on whether the PRD is good. + +- Glossary drift (case, plural, synonyms across the PRD). +- ID continuity (gaps, duplicates, unresolved cross-references). +- Assumptions Index roundtrip (every inline `[ASSUMPTION]` indexed; index entries all appear inline). +- UJ persona linkage (each UJ names a defined persona by exact label). +- Required sections present for the agreed stakes and product type. diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/validation-report-template.html b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/validation-report-template.html index 1e3136607..72e727162 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/validation-report-template.html +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/validation-report-template.html @@ -1,8 +1,30 @@ + -PRD Validation: $prd_name +PRD Validation: TEMPLATE_PRD_NAME