feat(bmad-prd): voice rules, probing reference, and operational hardening

- 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
This commit is contained in:
Brian Madison 2026-05-13 20:25:22 -05:00
parent 5090cfb096
commit dd6c605b4b
3 changed files with 88 additions and 25 deletions

View File

@ -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.

View File

@ -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

View File

@ -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.