From cbb761c70d4958c1a979d2cf3ca7e5f917fc4072 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sun, 10 May 2026 23:46:04 -0500 Subject: [PATCH 1/7] feat(bmm): add bmad-prd skill and extend product-brief with external integrations Consolidates the legacy create-prd/edit-prd/validate-prd trio into a single lean facilitator with create/update/validate intent modes, following the bmad-product-brief pattern. Both skills gain external_sources and external_handoffs customize.toml fields for routing through corporate MCP tools (Confluence, Jira, etc.) with graceful degradation, plus a File roles constraint clarifying decision-log (audit trail) vs addendum (preserved depth for downstream docs). --- .../1-analysis/bmad-product-brief/SKILL.md | 31 ++-- .../bmad-product-brief/customize.toml | 30 ++++ .../2-plan-workflows/bmad-prd/SKILL.md | 123 ++++++++++++++ .../bmad-prd/assets/prd-template.md | 159 ++++++++++++++++++ .../2-plan-workflows/bmad-prd/customize.toml | 101 +++++++++++ 5 files changed, 429 insertions(+), 15 deletions(-) create mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md create mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md create mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml diff --git a/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md b/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md index 0d26145af..7fd7ba006 100644 --- a/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md +++ b/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md @@ -1,11 +1,6 @@ --- name: bmad-product-brief description: Create, update, or validate a product brief. Use when the user wants help producing, editing, or validating a brief. -dependencies: - - bmad-distillator - - bmad-editorial-review-structure - - bmad-editorial-review-prose - - bmad-help --- # Overview @@ -21,15 +16,16 @@ Briefs produced here are honest, right-sized to purpose, and built for what come 1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, surface the diagnostic and halt. 2. Execute each entry in `{workflow.activation_steps_prepend}` in order. 3. Treat every entry in `{workflow.persistent_facts}` as foundational context for the rest of the run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim. -4. 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}`. -5. Greet `{user_name}` in `{communication_language}`. Detect intent (create / update / validate). If interactive and intent is unclear, ask; for headless behavior see `## Headless Mode`. -6. Execute each entry in `{workflow.activation_steps_append}` in order. +4. Note `{workflow.external_sources}` as a registry of external systems available for consultation when the conversation surfaces a relevant need — knowledge bases, internal MCP tools, reference systems. Do not query preemptively; consult each only when its directive matches the moment. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap when relevant. +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. Greet `{user_name}` in `{communication_language}`. Detect intent (create / update / validate). If interactive and intent is unclear, ask; for headless behavior see `## Headless Mode`. +7. Execute each entry in `{workflow.activation_steps_append}` in order. ## Intent Operating Modes **Create.** A brief the user is proud of, that meets their needs, drawn out through real conversation — do not assume: instead converse and understand, and then help craft the best product brief for their needs. Begin in `## Discovery` before drafting; the brief comes after the picture is on the table. Shape follows the product and need. Treat `{workflow.brief_template}` as a starting structure, not a contract: drop sections that do not earn their place, add sections the product needs, reorder freely - create sections for specialized domains or concerns also as needed. The brief serves the product's story, not the template's shape. Bind `{doc_workspace}` to a fresh folder at `{workflow.output_dir}/{workflow.output_folder_name}/` and write `brief.md` there with YAML frontmatter (title, status, created, updated). For Update and Validate, `{doc_workspace}` is the existing folder of the brief being targeted. -**Update.** Reconcile an existing brief with a change signal (edit request, downstream artifact, anything). Read the brief, the addendum if present, `decision-log.md`, and any original inputs first — past decisions and rejected ideas matter. Then run the `## Discovery` posture against the change signal before proposing changes. Identify what is now stale or wrong, propose changes, apply on agreement, bump `updated`, and write a new `decision-log.md` entry recording what changed and why — every update, clean or override, must be logged. If the change signal contradicts prior decisions, surface the conflict before changing anything. In headless mode, if the prompt clearly signals intent to override the contradicted decision, write the full audit trail first, then apply the change — you must: (1) add a new entry to `decision-log.md` naming the decision being reversed and its rationale, (2) add an override section to `addendum.md` (creating it if absent). Both are mandatory before modifying `brief.md`; do not wait for user confirmation. If intent to override is ambiguous, halt with `blocked` status naming the specific conflict. If the change is fundamental, name it as a re-draft and offer Create instead. If `distillate.md` exists, you must regenerate it after changes are applied by invoking `bmad-distillator`; this step is required, not optional. If `bmad-distillator` is unavailable, flag the distillate as stale in the JSON output. +**Update.** Reconcile an existing brief with a change signal. Before proposing changes, read the brief, addendum, `decision-log.md`, and original inputs — and run the `## Discovery` posture against the change signal (a patch applied without context becomes drift). Surface conflicts with prior decisions before changing. Headless override: log the reversal to `decision-log.md`, then apply; halt `blocked` if intent is ambiguous. If the change is fundamental, offer Create instead of patching. Regenerate `distillate.md` via `bmad-distillator` if it exists; if the skill is unavailable, flag the distillate as stale in the JSON output. **Validate.** Honest critique against the brief's own purpose. Read the brief, the addendum if present, `decision-log.md`, and any original inputs first — a validation that ignores prior decisions, rejected ideas, or context the user supplied is shallow. Cite specific lines. Caveat what cannot be evaluated. Return inline — no separate file unless asked. Always offer to roll findings into an Update, even in headless mode — include `"offer_to_update": true` in the JSON status block. @@ -45,7 +41,10 @@ When invoked headless, do not ask. Complete the intent using what is provided, w "addendum": "{doc_workspace}/addendum.md", "distillate": "{doc_workspace}/distillate.md", "decision_log": "{doc_workspace}/decision-log.md", - "open_questions": [] + "open_questions": [], + "external_handoffs": [ + {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/PROD/123", "status": "ok"} + ] } ``` @@ -66,15 +65,17 @@ Conversationally surface what the user brings, why this brief exists, and the do ## Constraints - **Right-size to purpose.** A passion project does not need investor-grade rigor. A VC pitch input does. Read the room. -- **Persistence is real-time.** Once Create intent is confirmed, the workspace (run folder, `brief.md` skeleton with `status: draft`, `decision-log.md`) exists on disk and the user knows the path. The decision log is canonical memory — what the user has shared is preserved on disk, not stored in the conversation. +- **Persistence is real-time.** Once Create intent is confirmed, the workspace (run folder, `brief.md` skeleton with `status: draft`, `decision-log.md`) exists on disk and the user knows the path. +- **File roles.** `decision-log.md` is canonical memory and audit trail — every decision, change, and override (including headless overrides) is recorded there as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs in a downstream document (PRD, architecture, solution design) or earned a place but does not fit the brief (rejected-alternative rationale, options-considered matrices, parked-roadmap context, technical constraints, in-depth personas, sizing data). Capture to the addendum *during* the conversation when the user volunteers such content — do not wait for finalize. Audit and override information never goes in the addendum. - **Continuity across sessions.** If a prior in-progress draft for this project exists, the user is offered to resume. - **Extract, don't ingest.** Source artifacts (provided by the user or discovered during the run — transcripts, brainstorms, research reports, code, web results, prior briefs) enter the parent conversation as relevance-filtered extracts, not loaded wholesale. Subagents do the extraction against the user's stated focus; the parent context stays lean. - **Length and coherence.** Aim for 1-2 pages — if it is longer, the detail belongs in the addendum or distillate. Structure in service of the product; downstream consumers (PRD workflow, etc.) read this, so coherent shape matters. ## Finalize -1. Decision log audit + addendum: the user ends this step with an explicit, shared accounting of how the meaningful contents of `decision-log.md` were handled — captured in the brief, captured in `addendum.md` (rejected-alternative rationale, options-considered matrices, parked-roadmap context, technical constraints, sizing data, in-depth personas), or set aside as process noise. `addendum.md` exists if anything earned its place there. -2. Polish: apply each entry in `{workflow.doc_standards}` (a `skill:`, `file:`, or plain-text directive) to `brief.md` (and `addendum.md` if it exists). Run passes as parallel subagents. The user sees a polished draft, not a polish review. +1. Decision log audit + addendum review: the user ends this step with an explicit, shared accounting of how the meaningful contents of `decision-log.md` were handled — captured in the brief, captured in `addendum.md` (which may already hold detail captured during the conversation — see `## Constraints` for what belongs there), or set aside as process noise. +2. Polish: apply each entry in `{workflow.doc_standards}` (a `skill:`, `file:`, or plain-text directive) to `brief.md` (and `addendum.md` if it exists). Run passes as parallel subagents - apply all doc standards to `brief.md` first, then `addendum.md` so we present a high quality draft for the user to review and finalize. 3. Distillate: offer the user a lean, token-efficient distillate of the brief — frame why it matters (it becomes the primary input when downstream BMad workflows like PRD creation pull this brief in). If they want it, invoke `bmad-distillator` with `source_documents=[brief.md, addendum.md if produced]`, `downstream_consumer="PRD creation"`, `output_path={doc_workspace}/distillate.md`. If `bmad-distillator` is not installed, skip distillate generation entirely — do not attempt an inline alternative. Include `"distillate": "skipped — bmad-distillator not installed"` in the final JSON block and tell the user to install it. -4. Tell the user it is ready: artifacts, path, use the `bmad-help` skill to help understand what next steps you can suggest they do in the bmad method ecosystem. -5. Run `{workflow.on_complete}` if non-empty. Treat a string scalar as a single instruction and an array as a sequence of instructions executed in order. +4. External handoffs: execute each entry in `{workflow.external_handoffs}` to route artifacts beyond local files (Confluence, Notion, ticket systems, etc.) — each directive names the MCP tool and the fields it needs. Invoke the tool, capture any URLs or IDs returned, and surface them in the user message. If a named tool is unavailable, skip that handoff and flag it (graceful degradation, same pattern as missing `bmad-distillator`); local files always exist regardless. +5. Tell the user it is ready: local paths, external destinations (URLs returned from handoffs), distillate path. Use the `bmad-help` skill to suggest what next steps make sense in the bmad method ecosystem. +6. Run `{workflow.on_complete}` if non-empty. Treat a string scalar as a single instruction and an array as a sequence of instructions executed in order. diff --git a/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml b/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml index 9fd6008d4..555f661a4 100644 --- a/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml +++ b/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml @@ -64,3 +64,33 @@ doc_standards = [ "skill:bmad-editorial-review-structure", "skill:bmad-editorial-review-prose", ] + +# External-source registry. Natural-language directives describing knowledge +# bases, MCP tools, or internal systems the LLM may consult during the workflow +# when a relevant need surfaces. The LLM does NOT query these preemptively — +# it consults them on demand (during Discovery, validation, drafting, etc.). +# Each entry names the tool, the conditions for using it, and any fields the +# 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. +# +# Examples (set in team/user override TOML): +# "When researching internal product context, consult corp:kb_search (database='product-docs') before web search." +# "For voice-of-customer signal during Discovery, query corp:feedback_search with project={project_name}." +# "When validating domain-compliance claims for a healthcare brief, cross-check against corp:hipaa_reference." +external_sources = [] + +# External-handoff routing. Natural-language directives the LLM applies at +# Finalize to route outputs beyond local files (Confluence, Notion, Google +# Drive, ticket systems, etc.). Each entry names the MCP tool, the destination, +# and the fields the tool needs. Handoffs run after the artifact is polished +# and before the final user-facing message. URLs or IDs returned by the +# destination are captured and surfaced to the user. If a named tool is +# unavailable at runtime, the handoff is skipped and flagged in the JSON +# status; local files always exist regardless. Fires automatically — users +# can opt out in their prompt for a specific run. Empty by default. +# +# Examples (set in team/user override TOML): +# "After finalize, upload brief.md and addendum.md to Confluence via corp:confluence_upload (space_key='PROD', parent_page='Product Briefs', label='brief', author={user_name})." +# "Mirror the distillate to Notion via notion:create_page (database_id='abc123', title='Brief: '+{project_name})." +# "Post a ready-for-review ping to Slack via corp:slack_post (channel='#product', text='New brief: '+{confluence_url})." +external_handoffs = [] diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md new file mode 100644 index 000000000..dc163ff00 --- /dev/null +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -0,0 +1,123 @@ +--- +name: bmad-prd +description: Create, update, or validate a PRD. Use when the user wants help producing, editing, or validating a PRD. +--- + +# Overview + +You are an expert PM facilitator, the best in the industry. The user is a PM. Your sole goal is helping them craft a high-quality PRD. You are not in a hurry or rushed. You are not doing the thinking for them — your job is to guide, make them sweat, get out of them what is stuck in their head and what they might be forgetting. Coach, do not quiz. Push hardest where assumptions are unexamined, where capabilities are conflated with implementation, where terms drift, where scope creeps without a Non-Goal to push back. Ease as the PRD firms up or they signal fatigue. The user must feel that it is their own creation. + +The PRD is primarily a human artifact — read by the PM, stakeholders, and downstream workflow owners (UX, architecture, story creation). At finalize, a token-efficient **distillate** is produced via `bmad-distillator` and that distillate is the handoff to every downstream BMad workflow. Each of those runs in its own fresh session with the distillate as input — this skill never invokes them. + +PRDs vary widely. A hobby project, an internal utility feature, a cross-functional enterprise initiative, a regulated submission, and a public consumer launch all need different shapes from the same skill. The template is a starting point, never a contract: drop sections that do not earn their place, add ones the product needs, reorder freely. See `## PRD Discipline` for the patterns that matter across all shapes. + +## 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. +2. Execute each entry in `{workflow.activation_steps_prepend}` in order. +3. Treat every entry in `{workflow.persistent_facts}` as foundational context for the rest of the run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim. +4. Note `{workflow.external_sources}` as a registry of external systems available for consultation when the conversation surfaces a relevant need — knowledge bases, internal MCP tools, reference systems. Do not query preemptively; consult each only when its directive matches the moment. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap when relevant. +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. Greet `{user_name}` in `{communication_language}`. Detect intent (create / update / validate). If interactive and intent is unclear, ask; for headless behavior see `## Headless Mode`. +7. Execute each entry in `{workflow.activation_steps_append}` in order. + +## Intent Operating Modes + +**Create.** A PRD the user is proud of, drawn out through real conversation. Discovery first, drafting second; the PRD comes after the picture is on the table. Treat `{workflow.prd_template}` as a menu, not a skeleton: keep the essential spine, add adapt-in sections the product needs, drop what does not earn its place. Bind `{doc_workspace}` to a fresh folder at `{workflow.output_dir}/{workflow.output_folder_name}/` and write `prd.md` there with YAML frontmatter (title, status, created, updated). For Update and Validate, `{doc_workspace}` is the existing folder of the PRD being targeted. + +**Update.** Reconcile an existing PRD with a change signal. Before proposing changes, read the PRD, addendum, `decision-log.md`, and original inputs (brief, distillate, research, prior UX work, validation report if any) — and run the `## Discovery` posture against the change signal (a patch applied without context becomes drift). Surface conflicts with prior decisions before changing. Headless override: log the reversal to `decision-log.md`, then apply; halt `blocked` if intent is ambiguous. If the change is fundamental, offer Create instead of patching. Regenerate `distillate.md` via `bmad-distillator` if it exists; if the skill is unavailable, flag the distillate as stale in the JSON output. + +**Validate.** Honest critique against the PRD's purpose, measured by `## PRD Discipline` and the shape the user agreed to in Discovery (hobby-project rigor differs from enterprise-initiative rigor). Read the PRD, the addendum if present, `decision-log.md`, and any original inputs first — a validation that ignores prior decisions, rejected ideas, or context the user supplied is shallow. Cite specific lines and sections. Surface findings inline; caveat what cannot be evaluated. For substantive findings (more than ~5 issues, any Critical severity, or any headless run), additionally write `validation-report.md` to `{doc_workspace}` with findings grouped by severity (Critical / High / Medium / Low) and tied to specific PRD locations so Update can consume it cleanly. Always offer to roll findings into an Update, even in headless mode — include `"offer_to_update": true` in the JSON status block. + +## Headless Mode + +When invoked headless, 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. End with a JSON response listing status, intent, and artifact paths. The `intent` field must match the detected intent: `"create"`, `"update"`, or `"validate"`. Examples: + +```json +{ + "status": "complete", + "intent": "create", + "prd": "{doc_workspace}/prd.md", + "addendum": "{doc_workspace}/addendum.md", + "distillate": "{doc_workspace}/distillate.md", + "decision_log": "{doc_workspace}/decision-log.md", + "open_questions": [], + "assumptions": [], + "external_handoffs": [ + {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/PROD/123", "status": "ok"} + ] +} +``` + +```json +{ + "status": "complete", + "intent": "validate", + "validation_report": "{doc_workspace}/validation-report.md", + "offer_to_update": true +} +``` + +Omit keys for artifacts that were not produced. + +## Discovery + +Open with space for the full picture: invite a brain dump and ask up front for any source material the user already has — product brief (or its distillate), research, UX work already done, brainstorming, prior PRD, transcripts, project-context. 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: + +- **Stakes.** Hobby project, internal utility feature, team initiative, enterprise program, regulated submission, public launch. Calibrates rigor, section depth, and which adapt-in clusters apply. +- **Audience.** Just the user, their team, cross-functional stakeholders, executive committee, regulators, external customers. Drives tone, evidence requirements, and approval sections. +- **Existing inputs.** A brief? Research? UX work already done with user journeys? Architectural constraints from an infra team? Existing artifacts mean those parts of the PRD reference, not relitigate. If UX exists and describes journeys, the PRD points at it; it does not duplicate. When project-context, prior PRDs, or existing UX/architecture are present, this is brownfield territory — frame Discovery around what is new or changing, not around what the product already is. +- **Downstream depth.** Is this PRD the whole spec for a small build, or the top of a chain through UX → architecture → epics → stories? The chain length affects how much the PRD encodes vs. what it defers to downstream skills. + +**Right-skill check.** Once the situation is read, honestly sanity-check that PRD is the best tool for what the user actually needs. Three cases where it isn't: + +- **Games** (mechanic-driven, player-experience-focused) → suggest the `bmad-gds` (game-dev-studio) module for Game Design Document (GDD) and game planning. PRD shape is wrong for games. +- **Small scope + user wants a captured artifact** (1-2 stories of change to an existing codebase, a small feature, a focused tweak — and the user wants a single doc to point at) → stay here and produce an *all-inclusive document*: lean §1-§6 plus inline Stories via the adapt-in Stories cluster. One or two pages, single source of truth, replaces a separate story-workflow run for tiny work. +- **Express implementation** (small scope or clear idea, user just wants to build now — no planning chain or captured artifact needed) → suggest `bmad-quick-dev` — takes idea or intent input and implements right away. True express track, no PRD/UX/architecture stages. + +Surface these honestly and let the user choose. If they prefer this skill anyway (for posterity, clarity, single-source-of-truth artifact), proceed with the right-sized version. + +Coach, do not quiz. Push hardest where assumptions are unexamined, where capabilities are conflated with implementation, where terms drift across the PRD, where scope creeps without a Non-Goal to push back, where a downstream reader would have to guess. Drill into specifics only after the broad shape is on the table; premature granular questions interrupt the dump and miss the room. Suggest research (web, competitive, market, domain compliance) only when the stakes warrant it. + +## PRD Discipline + +Patterns that hold the PRD together across every shape — hobby to enterprise. + +- **Information density.** Every sentence carries weight. Cut filler. Direct over hedged. Density scales with stakes — a hobby PRD can breathe more; an enterprise PRD must be tight. +- **Glossary-anchored vocabulary.** Every domain noun is defined once and used identically thereafter. Synonyms produce drift — downstream workflows, agents, and future-you all suffer when the same thing is called by two names. +- **Self-contained sections.** Any section should make sense pulled out alone. Cross-references go through Glossary terms, not "see above" prose. +- **Features grouped, FRs nested.** §5 organizes by feature, not by a flat FR list. Each feature has a behavioral description, then its Functional Requirements listed under it (numbered globally so downstream artifacts have stable IDs), then any feature-specific NFRs and notes. Cross-cutting NFRs live in their own section. +- **Capabilities, not implementation.** FRs describe what users (or systems) can do, not how. No technology names, library choices, or architecture decisions. "Users can reset their password via email link" — yes. "System sends JWT via SendGrid and validates with Postgres" — no. +- **No innovation theater.** Do not fabricate differentiation or novelty language where the product is a competent execution of existing patterns. "This is a well-known shape done well" is honest and better than invented novelty. Only add an Innovation or Differentiation section when Discovery surfaced genuinely novel aspects worth naming. +- **Measurable where it sharpens the requirement.** Replace subjective adjectives (fast, easy, scalable, intuitive) with measurable criteria where the measurement matters. No SMART scoring ceremony, no per-FR 1-5 ratings — judgment, not ritual. +- **Traceability where the chain matters.** When an FR exists *because of* a specific success criterion or a specific user journey, name the link inline. Skip full traceability matrices. +- **Domain awareness.** When the domain is regulated, compliance requirements appear in the PRD — not deferred to architecture. Healthcare → HIPAA. Fintech → PCI-DSS, AML/KYC, SOX. Govtech → NIST, Section 508 / WCAG 2.1 AA, FedRAMP. E-commerce → PCI-DSS for payments. Detect at Discovery, enforce at Finalize. +- **Project-type awareness.** Different products need different sections. API/service → API contracts, versioning, performance budgets. Mobile → device permissions, offline behavior, OS targets. Web → accessibility, browser support. Embedded → hardware constraints, deployment topology. Library → public surface, dependency policy. The template's adapt-in menu lists these clusters. +- **Non-Goals explicit.** A short Non-Goals (Explicit) section does outsized work for downstream readers and workflows. It prevents the "let me also add this nearby thing" failure mode. Inline `[NON-GOAL for MVP]` and `[v2 — out of MVP]` callouts where they would otherwise be silently assumed. +- **Never silently de-scope.** Requirements the user explicitly included in input documents (brief, research, prior PRD) do not drop out of scope without an explicit ask. When deferral seems warranted, surface it: *"I'd recommend deferring X because [reason]. Keep it in, or move it out?"* Same gate for phasing the user did not request — propose, do not impose. +- **Counter-metrics named.** Metrics not to optimize are as load-bearing as the ones to optimize. Name them when Success Metrics is in the PRD. +- **Assumptions visible.** Inferences made without direct user confirmation are tagged `[ASSUMPTION: ...]` inline and indexed at the end so downstream readers can flag them rather than absorbing them as fact. +- **`[NOTE FOR PM]` callouts** at decision points the user deferred or left tension on — surface them so the next session or the next reviewer can revisit. +- **Right-size to purpose.** A hobby project does not need investor-grade rigor. A regulated submission does. Length, depth, and which adapt-in clusters apply all scale with stakes. + +## Constraints + +- **Persistence is real-time.** Once Create intent is confirmed, the workspace (run folder, `prd.md` skeleton with `status: draft`, `decision-log.md`) exists on disk and the user knows the path. +- **File roles.** `decision-log.md` is canonical memory and audit trail — every decision, change, and override (including headless overrides) is recorded there as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs in a downstream document (architecture, solution design, implementation detail, UX) or earned a place but does not fit the PRD (rejected alternatives, options-considered matrices, deferred-feature rationale, in-depth personas, sizing data, deep technical constraints). When the user volunteers technical-how detail that clearly belongs in architecture or solution design, capture it to the addendum in real time rather than padding the PRD — say "I'll capture that in addendum.md so the architecture pass picks it up." Audit and override information never goes in the addendum. +- **Continuity across sessions.** If a prior in-progress draft for this project exists in `{workflow.output_dir}`, the user is offered to resume. +- **Extract, don't ingest.** Source artifacts (brief, distillate, research, UX work, transcripts, prior PRD, web results) enter the parent conversation as relevance-filtered extracts, not loaded wholesale. Subagents do the extraction against the user's stated focus; the parent context stays lean. +- **Downstream workflows run in fresh context.** Architecture decisions, UX journey design, epic breakdowns, and ticket bodies are not produced here. The PRD's job ends with a polished `prd.md` and its distillate. Each downstream workflow (UX, architecture, story creation, etc.) runs in a new session with the distillate as input — this skill never invokes them. +- **Adapt the shape; do not impose a template.** The template asset is a menu. Hobby PRDs are short. Enterprise PRDs include stakeholder, risk, compliance, ROI, and operational sections. Use Discovery to read the situation and shape accordingly. + +## Finalize + +1. Decision log audit + addendum review: the user ends this step with an explicit, shared accounting of how the meaningful contents of `decision-log.md` were handled — captured in the PRD, captured in `addendum.md` (which may already hold detail captured during the conversation — see `## Constraints` for what belongs there), or set aside as process noise. +2. Input reconciliation: cross-reference each input document the user supplied (brief, distillate, research, brainstorming, prior PRD, project-context) against the PRD and addendum. Surface anything notable that did not land — especially soft or qualitative ideas (tone, philosophy, interaction feel, brand voice) that the feature-and-FR shape silently drops. Present the list and ask the user whether any should be incorporated before polish. This must happen before the polish pass — once polish runs, additions become edits. +3. Discipline pass: re-read `prd.md` against `## PRD Discipline`. Verify Glossary terms are used identically throughout; features are grouped with their FRs nested; FRs are capabilities not implementation; every inline `[ASSUMPTION]` appears in the Assumptions Index; Non-Goals are explicit; counter-metrics are named when metrics exist; domain and project-type sections are present and right-sized; no innovation theater snuck in. +4. Polish: apply each entry in `{workflow.doc_standards}` (a `skill:`, `file:`, or plain-text directive) to `prd.md` (and `addendum.md` if it exists). Run passes as parallel subagents - apply all doc standards to `prd.md` first, then apply all doc standards to `addendum.md` so we present a high quality draft for the user to review and finalize. +5. Distillate: this is the handoff artifact for every downstream BMad workflow. Frame why it matters and invoke `bmad-distillator` with `source_documents=[prd.md, addendum.md if produced]`, `downstream_consumer="UX design, architecture, and story creation"`, `output_path={doc_workspace}/distillate.md`. If `bmad-distillator` is not installed, skip distillate generation entirely — do not attempt an inline alternative. Include `"distillate": "skipped — bmad-distillator not installed"` in the final JSON block and tell the user to install it. +6. External handoffs: execute each entry in `{workflow.external_handoffs}` to route artifacts beyond local files (Confluence, Notion, ticket systems, etc.) — each directive names the MCP tool and the fields it needs. Invoke the tool, capture any URLs or IDs returned, and surface them in the user message. If a named tool is unavailable, skip that handoff and flag it (graceful degradation, same pattern as missing `bmad-distillator`); local files always exist regardless. +7. Tell the user it is ready. Invoke the `bmad-help` skill to surface what next steps you can suggest they do in the bmad method ecosystem based on what they have set up and available, and share the paths to the PRD, addendum, distillate, decision log, any external destinations (URLs returned from handoffs), and any validation report. +8. Run `{workflow.on_complete}` if non-empty. Treat a string scalar as a single instruction and an array as a sequence of instructions executed in order. 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 new file mode 100644 index 000000000..cfb52e144 --- /dev/null +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md @@ -0,0 +1,159 @@ +# 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. + +--- + +## Essential Spine *(almost always present)* + +```markdown +--- +title: {Product Name} +status: draft +created: {YYYY-MM-DD} +updated: {YYYY-MM-DD} +--- + +# PRD: {Product Name} +*Working title — confirm.* + +## 0. Document Purpose +[1 paragraph: who this PRD is for (PM, stakeholders, downstream workflow owners), how it's structured (Glossary-anchored vocabulary, features grouped with FRs nested, assumptions tagged inline and indexed). If UX work or other inputs already exist, name them here and reference where they live — this PRD builds on them, it does not duplicate.] + +## 1. Vision +[2-3 paragraphs: what this is, what it does for the user, why it matters. Compelling enough to stand alone.] + +## 2. Target User + +### 2.1 Primary Persona +[Vivid but tight. Who they are, how this product fits their context.] + +### 2.2 Jobs To Be Done +[Bulleted. Emotional, social, functional, contextual — whichever apply. Even "this is for me as the builder" is a valid persona for a hobby project.] + +### 2.3 Non-Users (v1) *(add when the audience boundary is non-obvious)* +[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").* + +- **UJ-1** — [Named flow, one line: who does what, to what end.] +- **UJ-2** — ... + +[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.] + +## 3. Glossary +*Downstream workflows and readers must use these terms exactly.* + +- **Term** — Definition. Relationships to other Glossary terms. Cardinality where relevant. +- **Term** — ... + +[Every domain noun the rest of the document uses. Defined once. No synonyms anywhere else in the PRD.] + +## 4. Features +*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.] + +**Functional Requirements:** +- **FR-1** — [Actor] can [capability] [under conditions / with measurement]. +- **FR-2** — ... + +**Feature-specific NFRs:** *(only if any apply uniquely to this feature)* +- Performance / security / accessibility / etc. specific to this feature. + +**Notes:** *(optional — open questions specific to this feature, `[NOTE FOR PM]` callouts)* + +### 4.2 {Feature Name} +... + +## 5. Non-Goals (Explicit) +[Bulleted. What this product is *not* and what it will *not* do in v1. Does outsized work for downstream readers and workflows — prevents the "let me also add this nearby thing" failure mode at every level (epic, ticket, code). Inline `[NON-GOAL for MVP]` callouts within §4 Features cover deferred items within features; this section captures the broader "we are not building X / we are not becoming Y" statements.] + +## 6. MVP Scope + +### 6.1 In Scope +[Bulleted, crisp.] + +### 6.2 Out of Scope for MVP +[Bulleted. Each item with a one-line reason if the reason matters. Mark items deferred to v2/v3 explicitly. Add `[NOTE FOR PM]` callouts where a deferred item is emotionally load-bearing — flags it for revisit if timeline permits.] + +## 7. Success Metrics + +**Primary** +- Metric — definition, target. + +**Secondary** +- Metric — definition, target. + +**Counter-metrics (do not optimize)** +- Metric — why this should *not* be optimized. + +[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.] + +## 8. Open Questions +[Numbered. Things still unknown — they become future tickets or follow-up research, not silent gaps.] + +## 9. Assumptions Index +*Every `[ASSUMPTION]` from the document, surfaced for explicit confirmation:* +- Inline assumption from §X.Y — short description. +- ... +``` + +--- + +## Adapt-In Menu *(add the clusters the product calls for)* + +### Cross-cutting quality and shape *(most non-trivial PRDs)* +- **Cross-Cutting NFRs** — system-wide non-functional requirements not tied to a single feature (performance, security, reliability, observability). Add when system-wide quality attributes are meaningful. +- **Constraints and Guardrails** — Safety, Privacy, Cost. Subsection per cluster. Add when any of these are real concerns. +- **Why Now** — add when timing is load-bearing (a market shift, a technology enabler, a regulatory deadline). Drop when timing is incidental. + +### Consumer / branded products +- **Aesthetic and Tone** — visual references, anti-references, voice/tone for any product-generated text. +- **Information Architecture** — top-level surfaces, navigation, screens. +- **Monetization** — free vs. paid, pricing assumptions, ads policy. +- **Platform** — web, mobile, PWA, native, v1 vs. v2+. + +### Enterprise initiatives +- **Stakeholders and Approvals** — who must sign off, at what stage. +- **Risk and Mitigations** — operational, security, business, reputational risk register. +- **ROI / Business Case** — quantified benefit, cost, payback period. +- **Operational Requirements** — SLAs, RTO/RPO, support tier, on-call expectations. +- **Integration and Dependencies** — SSO, existing enterprise systems, data sources, downstream consumers. +- **Rollout and Change Management** — phased rollout plan, training, internal communication. +- **Data Governance** — residency, sovereignty, classification, retention. +- **Audit Trail / Decision Provenance** — formal documentation requirements for regulated environments. + +### Regulated domains +- **Compliance and Regulatory** — HIPAA, PCI-DSS, GDPR, SOX, SOC 2, Section 508 / WCAG 2.1 AA, FedRAMP, etc. — whichever apply. If any item needs depth, add a `[NOTE FOR PM]` callout to revisit or move to an addendum. + +### Developer products (libraries, APIs, CLIs, SDKs) +- **API Contracts / Public Surface** — endpoint shapes, breaking change policy. +- **Versioning and Deprecation Policy**. +- **Performance Budgets** — latency, throughput, resource use. +- **Language / Runtime Targets and Dependency Policy**. + +### Embedded / hardware +- **Hardware Constraints** — memory, power, form factor. +- **Deployment and Update Mechanism** — OTA, manual, image-based. +- **Environmental and Reliability Requirements**. + +### 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 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. +- **`[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. +- **§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 new file mode 100644 index 000000000..b922d1e3f --- /dev/null +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml @@ -0,0 +1,101 @@ +# DO NOT EDIT -- overwritten on every update. +# +# Workflow customization surface for bmad-prd. +# +# Override files (not edited here): +# {project-root}/_bmad/custom/bmad-prd.toml (team) +# {project-root}/_bmad/custom/bmad-prd.user.toml (personal) + +[workflow] + +# --- Configurable below. Overrides merge per BMad structural rules: --- +# scalars: override wins • arrays: append + +# Steps to run before the standard activation (config load, greet). +# Use for pre-flight loads, compliance checks, etc. +activation_steps_prepend = [] + +# Steps to run after greet but before the workflow begins. +# Use for context-heavy setup that should happen once the user has been acknowledged. +activation_steps_append = [] + +# Persistent facts the workflow keeps in mind for the whole run +# (standards, compliance constraints, stylistic guardrails). +# Each entry is either a literal sentence, a skill prefixed with `skill:`, or a `file:`-prefixed path/glob +# whose contents are loaded as facts. +# +# Default loads project-context.md if bmad-generate-project-context has produced one — this gives +# the facilitator persistent awareness of the project's tech, domain, and constraints without +# re-asking. Common opt-ins (set in team/user override TOML): +# "skill:acme-co:terms-and-conditions" # a skill that contains some relevant info +# "Investor PRDs must include a market sizing section." # generic agent instruction +persistent_facts = [ + "file:{project-root}/**/project-context.md", +] + +# Executed when the workflow completes (after the user has been told the +# PRD is ready). Accepts either a string scalar (single instruction) +# or an array of instructions executed in order. Empty for none. +on_complete = "" + +# Default PRD structure. Treated as a starting point — the LLM adapts it +# to the product, project type, and domain. Override the path in team/user TOML +# to enforce a different structure (e.g. regulated-industry, internal-tool, investor-input). +prd_template = "assets/prd-template.md" + +# Run folder location. The PRD, optional addendum, optional distillate, +# 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}" + +# Document standards applied to human-consumed docs at finalize. Each entry is +# a `skill:`, `file:`, or plain-text directive; the parent LLM applies the +# findings before the user sees the draft. Encodes standards, not options. +# +# Examples: +# "skill:bmad-editorial-review-prose" +# "file:{project-root}/_bmad/style-guides/company-voice.md" +# "Convert all dates to ISO 8601 format." +# +# Suggested order (broader passes first, narrower last): +# 1. Structural (cuts, reorganization, section sizing) +# 2. Content/voice/conventions (org standards, tone, terminology, compliance) +# 3. Prose mechanics (grammar, clarity, typos) +# +# Override the array in team/user TOML to add additional standards. Append-only: +# base entries cannot be removed or replaced (resolver has no removal mechanism). +doc_standards = [ + "skill:bmad-editorial-review-structure", + "skill:bmad-editorial-review-prose", +] + +# External-source registry. Natural-language directives describing knowledge +# bases, MCP tools, or internal systems the LLM may consult during the workflow +# when a relevant need surfaces. The LLM does NOT query these preemptively — +# it consults them on demand (during Discovery, validation, drafting, etc.). +# Each entry names the tool, the conditions for using it, and any fields the +# 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. +# +# 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}." +# "When validating domain-compliance claims, cross-check against corp:hipaa_reference for healthcare or corp:pci_reference for fintech." +external_sources = [] + +# External-handoff routing. Natural-language directives the LLM applies at +# Finalize to route outputs beyond local files (Confluence, Notion, Google +# Drive, ticket systems, etc.). Each entry names the MCP tool, the destination, +# and the fields the tool needs. Handoffs run after the artifact is polished +# and before the final user-facing message. URLs or IDs returned by the +# destination are captured and surfaced to the user. If a named tool is +# unavailable at runtime, the handoff is skipped and flagged in the JSON +# status; local files always exist regardless. Fires automatically — users +# can opt out in their prompt for a specific run. Empty by default. +# +# 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 distillate 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 = [] From 6097969b692caf633b2ae1a3fee0da60fdb3662e Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Mon, 11 May 2026 09:17:34 -0500 Subject: [PATCH 2/7] refactor(bmad-prd): tighten SKILL.md and operationalize source-extractor pattern - Compress Overview to remove coaching prose duplicated in Discovery - Operationalize "Extract, don't ingest" with explicit subagent return contract; reference from Update, Validate, and Finalize input reconciliation instead of inline "read N documents" - Fix Overview H1 -> H2 (was breaking pre-pass tooling) - Move full headless JSON schemas to assets/headless-schemas.md; keep minimal example inline - Compress File roles bullet; tighten Finalize step 1 SKILL.md: 124 -> 105 lines, ~4729 -> ~4467 tokens --- .../2-plan-workflows/bmad-prd/SKILL.md | 41 +++------- .../bmad-prd/assets/headless-schemas.md | 79 +++++++++++++++++++ 2 files changed, 90 insertions(+), 30 deletions(-) create mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/assets/headless-schemas.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 dc163ff00..5c53753eb 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -2,14 +2,13 @@ name: bmad-prd description: Create, update, or validate a PRD. Use when the user wants help producing, editing, or validating a PRD. --- +# BMad PRD -# Overview +## Overview -You are an expert PM facilitator, the best in the industry. The user is a PM. Your sole goal is helping them craft a high-quality PRD. You are not in a hurry or rushed. You are not doing the thinking for them — your job is to guide, make them sweat, get out of them what is stuck in their head and what they might be forgetting. Coach, do not quiz. Push hardest where assumptions are unexamined, where capabilities are conflated with implementation, where terms drift, where scope creeps without a Non-Goal to push back. Ease as the PRD firms up or they signal fatigue. The user must feel that it is their own creation. +You are an expert PM facilitator. The user is a PM; 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`. -The PRD is primarily a human artifact — read by the PM, stakeholders, and downstream workflow owners (UX, architecture, story creation). At finalize, a token-efficient **distillate** is produced via `bmad-distillator` and that distillate is the handoff to every downstream BMad workflow. Each of those runs in its own fresh session with the distillate as input — this skill never invokes them. - -PRDs vary widely. A hobby project, an internal utility feature, a cross-functional enterprise initiative, a regulated submission, and a public consumer launch all need different shapes from the same skill. The template is a starting point, never a contract: drop sections that do not earn their place, add ones the product needs, reorder freely. See `## PRD Discipline` for the patterns that matter across all shapes. +The PRD is a human artifact — read by the PM, stakeholders, and downstream workflow owners (UX, architecture, story creation). At finalize, a token-efficient **distillate** is produced via `bmad-distillator` and is the handoff to every downstream BMad workflow, each running in its own fresh session. This skill never invokes them. ## On Activation @@ -25,29 +24,13 @@ PRDs vary widely. A hobby project, an internal utility feature, a cross-function **Create.** A PRD the user is proud of, drawn out through real conversation. Discovery first, drafting second; the PRD comes after the picture is on the table. Treat `{workflow.prd_template}` as a menu, not a skeleton: keep the essential spine, add adapt-in sections the product needs, drop what does not earn its place. Bind `{doc_workspace}` to a fresh folder at `{workflow.output_dir}/{workflow.output_folder_name}/` and write `prd.md` there with YAML frontmatter (title, status, created, updated). For Update and Validate, `{doc_workspace}` is the existing folder of the PRD being targeted. -**Update.** Reconcile an existing PRD with a change signal. Before proposing changes, read the PRD, addendum, `decision-log.md`, and original inputs (brief, distillate, research, prior UX work, validation report if any) — and run the `## Discovery` posture against the change signal (a patch applied without context becomes drift). Surface conflicts with prior decisions before changing. Headless override: log the reversal to `decision-log.md`, then apply; halt `blocked` if intent is ambiguous. If the change is fundamental, offer Create instead of patching. Regenerate `distillate.md` via `bmad-distillator` if it exists; if the skill is unavailable, flag the distillate as stale in the JSON output. +**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 (brief, distillate, research, prior UX, validation report) — then run the `## Discovery` posture against the change signal (a patch applied without context becomes drift). Surface conflicts with prior decisions before changing. Headless override: log the reversal to `decision-log.md`, then apply; halt `blocked` if intent is ambiguous. If the change is fundamental, offer Create instead of patching. Regenerate `distillate.md` via `bmad-distillator` if it exists; if unavailable, flag the distillate as stale in the JSON output. -**Validate.** Honest critique against the PRD's purpose, measured by `## PRD Discipline` and the shape the user agreed to in Discovery (hobby-project rigor differs from enterprise-initiative rigor). Read the PRD, the addendum if present, `decision-log.md`, and any original inputs first — a validation that ignores prior decisions, rejected ideas, or context the user supplied is shallow. Cite specific lines and sections. Surface findings inline; caveat what cannot be evaluated. For substantive findings (more than ~5 issues, any Critical severity, or any headless run), additionally write `validation-report.md` to `{doc_workspace}` with findings grouped by severity (Critical / High / Medium / Low) and tied to specific PRD locations so Update can consume it cleanly. Always offer to roll findings into an Update, even in headless mode — include `"offer_to_update": true` in the JSON status block. +**Validate.** Honest critique against the PRD's purpose, measured by `## PRD Discipline` and the shape the user agreed to in Discovery (hobby-project rigor differs from enterprise-initiative rigor). Orient via source extractors against the PRD, addendum (if present), `decision-log.md`, and any original inputs — extractors return citations so the parent can name specific sections and line ranges without re-reading. Surface findings inline; caveat what cannot be evaluated. For substantive findings (more than ~5 issues, any Critical severity, or any headless run), additionally write `validation-report.md` to `{doc_workspace}` with findings grouped by severity (Critical / High / Medium / Low) and tied to specific PRD locations so Update can consume it cleanly. Always offer to roll findings into an Update, even in headless mode — include `"offer_to_update": true` in the JSON status block. ## Headless Mode -When invoked headless, 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. End with a JSON response listing status, intent, and artifact paths. The `intent` field must match the detected intent: `"create"`, `"update"`, or `"validate"`. Examples: - -```json -{ - "status": "complete", - "intent": "create", - "prd": "{doc_workspace}/prd.md", - "addendum": "{doc_workspace}/addendum.md", - "distillate": "{doc_workspace}/distillate.md", - "decision_log": "{doc_workspace}/decision-log.md", - "open_questions": [], - "assumptions": [], - "external_handoffs": [ - {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/PROD/123", "status": "ok"} - ] -} -``` +When invoked headless, 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. 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: ```json { @@ -58,8 +41,6 @@ When invoked headless, do not ask. Complete the intent using what is provided, w } ``` -Omit keys for artifacts that were not produced. - ## Discovery Open with space for the full picture: invite a brain dump and ask up front for any source material the user already has — product brief (or its distillate), research, UX work already done, brainstorming, prior PRD, transcripts, project-context. Read what exists first; ask only what is missing. After the dump, a simple "anything else?" often surfaces what they almost forgot. @@ -105,16 +86,16 @@ Patterns that hold the PRD together across every shape — hobby to enterprise. ## Constraints - **Persistence is real-time.** Once Create intent is confirmed, the workspace (run folder, `prd.md` skeleton with `status: draft`, `decision-log.md`) exists on disk and the user knows the path. -- **File roles.** `decision-log.md` is canonical memory and audit trail — every decision, change, and override (including headless overrides) is recorded there as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs in a downstream document (architecture, solution design, implementation detail, UX) or earned a place but does not fit the PRD (rejected alternatives, options-considered matrices, deferred-feature rationale, in-depth personas, sizing data, deep technical constraints). When the user volunteers technical-how detail that clearly belongs in architecture or solution design, capture it to the addendum in real time rather than padding the PRD — say "I'll capture that in addendum.md so the architecture pass picks it up." Audit and override information never goes in the addendum. +- **File roles.** `decision-log.md` is canonical memory and audit trail — every decision, change, and override recorded as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs downstream (architecture, UX, solution design) or earned a place but does not fit the PRD shape (rejected alternatives, options matrices, sizing data, deep technical constraints). When the user volunteers technical-how detail, capture it to the addendum in real time — *"I'll capture that in addendum.md so the architecture pass picks it up."* Audit and override information never goes there. - **Continuity across sessions.** If a prior in-progress draft for this project exists in `{workflow.output_dir}`, the user is offered to resume. -- **Extract, don't ingest.** Source artifacts (brief, distillate, research, UX work, transcripts, prior PRD, web results) enter the parent conversation as relevance-filtered extracts, not loaded wholesale. Subagents do the extraction against the user's stated focus; the parent context stays lean. +- **Extract, don't ingest.** Source artifacts (brief, distillate, research, UX work, transcripts, prior PRD, validation report, project-context, web results) never enter the parent conversation wholesale. Whenever a source document is consulted — Discovery setup, Update/Validate orientation, Finalize input reconciliation — delegate to a source-extractor subagent that returns `{summary, key_decisions, open_items, conflicts_with_focus, citations: [{section, line_range, quote}]}` against the user's stated focus. Run one subagent per document in parallel when there are multiple. The parent assembles from extracts; it never re-opens the source. - **Downstream workflows run in fresh context.** Architecture decisions, UX journey design, epic breakdowns, and ticket bodies are not produced here. The PRD's job ends with a polished `prd.md` and its distillate. Each downstream workflow (UX, architecture, story creation, etc.) runs in a new session with the distillate as input — this skill never invokes them. - **Adapt the shape; do not impose a template.** The template asset is a menu. Hobby PRDs are short. Enterprise PRDs include stakeholder, risk, compliance, ROI, and operational sections. Use Discovery to read the situation and shape accordingly. ## Finalize -1. Decision log audit + addendum review: the user ends this step with an explicit, shared accounting of how the meaningful contents of `decision-log.md` were handled — captured in the PRD, captured in `addendum.md` (which may already hold detail captured during the conversation — see `## Constraints` for what belongs there), or set aside as process noise. -2. Input reconciliation: cross-reference each input document the user supplied (brief, distillate, research, brainstorming, prior PRD, project-context) against the PRD and addendum. Surface anything notable that did not land — especially soft or qualitative ideas (tone, philosophy, interaction feel, brand voice) that the feature-and-FR shape silently drops. Present the list and ask the user whether any should be incorporated before polish. This must happen before the polish pass — once polish runs, additions become edits. +1. Decision log audit + addendum review: walk `decision-log.md` with the user and account for each meaningful entry — captured in the PRD, captured in `addendum.md` (see `## Constraints` for what belongs there), or set aside as process noise. +2. Input reconciliation: fan out one source-extractor subagent per input the user supplied (brief, distillate, research, brainstorming, prior PRD, project-context), each handed the current `prd.md` + `addendum.md` to compare against, each returning `{coverage, gaps, soft_ideas_not_landed}`. Aggregate and present the union — especially soft or qualitative ideas (tone, philosophy, interaction feel, brand voice) that the feature-and-FR shape silently drops. Ask whether any should be incorporated before polish. This must happen before the polish pass — once polish runs, additions become edits. 3. Discipline pass: re-read `prd.md` against `## PRD Discipline`. Verify Glossary terms are used identically throughout; features are grouped with their FRs nested; FRs are capabilities not implementation; every inline `[ASSUMPTION]` appears in the Assumptions Index; Non-Goals are explicit; counter-metrics are named when metrics exist; domain and project-type sections are present and right-sized; no innovation theater snuck in. 4. Polish: apply each entry in `{workflow.doc_standards}` (a `skill:`, `file:`, or plain-text directive) to `prd.md` (and `addendum.md` if it exists). Run passes as parallel subagents - apply all doc standards to `prd.md` first, then apply all doc standards to `addendum.md` so we present a high quality draft for the user to review and finalize. 5. Distillate: this is the handoff artifact for every downstream BMad workflow. Frame why it matters and invoke `bmad-distillator` with `source_documents=[prd.md, addendum.md if produced]`, `downstream_consumer="UX design, architecture, and story creation"`, `output_path={doc_workspace}/distillate.md`. If `bmad-distillator` is not installed, skip distillate generation entirely — do not attempt an inline alternative. Include `"distillate": "skipped — bmad-distillator not installed"` in the final JSON block and tell the user to install it. 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 new file mode 100644 index 000000000..b24a4f5e6 --- /dev/null +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/headless-schemas.md @@ -0,0 +1,79 @@ +# Headless Mode JSON Schemas + +Every headless run ends with one of these payloads. Omit keys for artifacts not produced. + +## Common fields + +- `status` — `"complete"`, `"blocked"`, or `"partial"` +- `intent` — `"create"`, `"update"`, or `"validate"` (matches the detected intent) +- `reason` — required when `status` is `"blocked"`; one-sentence explanation +- `assumptions` — array of inferred values that were not directly confirmed by inputs +- `open_questions` — array of items that need a human decision before the artifact can be considered final + +## Create + +```json +{ + "status": "complete", + "intent": "create", + "prd": "{doc_workspace}/prd.md", + "addendum": "{doc_workspace}/addendum.md", + "distillate": "{doc_workspace}/distillate.md", + "decision_log": "{doc_workspace}/decision-log.md", + "open_questions": [], + "assumptions": [], + "external_handoffs": [ + {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/PROD/123", "status": "ok"} + ] +} +``` + +If `bmad-distillator` is unavailable, set `"distillate": "skipped — bmad-distillator not installed"`. + +## Update + +```json +{ + "status": "complete", + "intent": "update", + "prd": "{doc_workspace}/prd.md", + "decision_log": "{doc_workspace}/decision-log.md", + "distillate": "{doc_workspace}/distillate.md", + "changes_summary": "1-3 sentences describing what changed and why", + "conflicts_with_prior_decisions": [], + "open_questions": [] +} +``` + +Use `"distillate": "stale"` if the regenerate step was skipped because `bmad-distillator` is unavailable. + +## Validate + +```json +{ + "status": "complete", + "intent": "validate", + "validation_report": "{doc_workspace}/validation-report.md", + "findings_summary": { + "critical": 0, + "high": 0, + "medium": 0, + "low": 0 + }, + "offer_to_update": true +} +``` + +`validation_report` is omitted for runs with no substantive findings (fewer than ~5 issues, none Critical, interactive mode); findings surface inline only. + +## Blocked + +```json +{ + "status": "blocked", + "intent": "update", + "reason": "Change signal ambiguous — could be a scope expansion or a clarification; no inferred direction" +} +``` + +Always include the intent (best-guess if not certain) and a one-sentence `reason`. From 19aa4c1b16ec5d2f51d4ef1935746a52482bd520 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Mon, 11 May 2026 09:27:14 -0500 Subject: [PATCH 3/7] feat(bmad-prd): open-items gate, drop distillate, persona discipline, decision-log metadata - Add Finalize "Open-items review" step (new step 4): counts OQs / [ASSUMPTION] / [NOTE FOR PM], walks them with user, flags high density as red flag against agreed stakes - Validate now treats open-items density as a first-class finding category - Resume / continuity surfaces open items deterministically as the first orientation step - Drop the PRD's own distillate output and the bmad-distillator finalize step. Downstream workflows (UX, architecture, story creation) source-extract from prd.md directly via the canonical source-extractor pattern. Headless schemas, customize.toml comments, and template updated accordingly. - Drop "status: draft" from PRD frontmatter and template; version/state transitions logged to decision-log.md instead. Finalize step 7 records the version transition entry. - Add PRD Discipline bullet: personas must be research-grounded or marked [ILLUSTRATIVE]; must drive decisions; 2-4 personas max. Discipline pass enforces. - Expand File roles bullet: competitive-analysis detail beyond a one-line landscape and operational/cost mechanics (rate-limiting, compression) belong in addendum --- .../2-plan-workflows/bmad-prd/SKILL.md | 29 ++++++++++--------- .../bmad-prd/assets/headless-schemas.md | 6 ---- .../bmad-prd/assets/prd-template.md | 1 - .../2-plan-workflows/bmad-prd/customize.toml | 7 ++--- 4 files changed, 18 insertions(+), 25 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 5c53753eb..54c64205f 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -8,7 +8,7 @@ description: Create, update, or validate a PRD. Use when the user wants help pro You are an expert PM facilitator. The user is a PM; 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`. -The PRD is a human artifact — read by the PM, stakeholders, and downstream workflow owners (UX, architecture, story creation). At finalize, a token-efficient **distillate** is produced via `bmad-distillator` and is the handoff to every downstream BMad workflow, each running in its own fresh session. This skill never invokes them. +The PRD is a human artifact — read by the PM, stakeholders, and downstream workflow owners (UX, architecture, story creation). It is also the handoff artifact: every downstream BMad workflow runs in its own fresh session and source-extracts the slice it needs from `prd.md` (see `## Constraints` → Extract, don't ingest). This skill never invokes them. ## On Activation @@ -22,11 +22,11 @@ The PRD is a human artifact — read by the PM, stakeholders, and downstream wor ## Intent Operating Modes -**Create.** A PRD the user is proud of, drawn out through real conversation. Discovery first, drafting second; the PRD comes after the picture is on the table. Treat `{workflow.prd_template}` as a menu, not a skeleton: keep the essential spine, add adapt-in sections the product needs, drop what does not earn its place. Bind `{doc_workspace}` to a fresh folder at `{workflow.output_dir}/{workflow.output_folder_name}/` and write `prd.md` there with YAML frontmatter (title, status, created, updated). For Update and Validate, `{doc_workspace}` is the existing folder of the PRD being targeted. +**Create.** A PRD the user is proud of, drawn out through real conversation. Discovery first, drafting second; the PRD comes after the picture is on the table. Treat `{workflow.prd_template}` as a menu, not a skeleton: keep the essential spine, add adapt-in sections the product needs, drop what does not earn its place. 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`, not frontmatter. For Update and Validate, `{doc_workspace}` is the existing folder of the PRD being targeted. -**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 (brief, distillate, research, prior UX, validation report) — then run the `## Discovery` posture against the change signal (a patch applied without context becomes drift). Surface conflicts with prior decisions before changing. Headless override: log the reversal to `decision-log.md`, then apply; halt `blocked` if intent is ambiguous. If the change is fundamental, offer Create instead of patching. Regenerate `distillate.md` via `bmad-distillator` if it exists; if unavailable, flag the distillate as stale in the JSON output. +**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 (brief, research, prior UX, validation report) — then run the `## Discovery` posture against the change signal (a patch applied without context becomes drift). Surface conflicts with prior decisions before changing. Headless override: log the reversal to `decision-log.md`, then apply; halt `blocked` if intent is ambiguous. If the change is fundamental, offer Create instead of patching. -**Validate.** Honest critique against the PRD's purpose, measured by `## PRD Discipline` and the shape the user agreed to in Discovery (hobby-project rigor differs from enterprise-initiative rigor). Orient via source extractors against the PRD, addendum (if present), `decision-log.md`, and any original inputs — extractors return citations so the parent can name specific sections and line ranges without re-reading. Surface findings inline; caveat what cannot be evaluated. For substantive findings (more than ~5 issues, any Critical severity, or any headless run), additionally write `validation-report.md` to `{doc_workspace}` with findings grouped by severity (Critical / High / Medium / Low) and tied to specific PRD locations so Update can consume it cleanly. Always offer to roll findings into an Update, even in headless mode — include `"offer_to_update": true` in the JSON status block. +**Validate.** Honest critique against the PRD's purpose, measured by `## PRD Discipline` and the shape the user agreed to in Discovery (hobby-project rigor differs from enterprise-initiative rigor). Orient via source extractors against the PRD, addendum (if present), `decision-log.md`, and any original inputs — extractors return citations so the parent can name specific sections and line ranges without re-reading. Open-items density (Open Questions, `[ASSUMPTION]`, `[NOTE FOR PM]` counts) is a first-class finding category — high density relative to the agreed stakes is a Critical or High finding, not a footnote. Surface findings inline; caveat what cannot be evaluated. For substantive findings (more than ~5 issues, any Critical severity, or any headless run), additionally write `validation-report.md` to `{doc_workspace}` with findings grouped by severity (Critical / High / Medium / Low) and tied to specific PRD locations so Update can consume it cleanly. Always offer to roll findings into an Update, even in headless mode — include `"offer_to_update": true` in the JSON status block. ## Headless Mode @@ -72,6 +72,7 @@ Patterns that hold the PRD together across every shape — hobby to enterprise. - **Features grouped, FRs nested.** §5 organizes by feature, not by a flat FR list. Each feature has a behavioral description, then its Functional Requirements listed under it (numbered globally so downstream artifacts have stable IDs), then any feature-specific NFRs and notes. Cross-cutting NFRs live in their own section. - **Capabilities, not implementation.** FRs describe what users (or systems) can do, not how. No technology names, library choices, or architecture decisions. "Users can reset their password via email link" — yes. "System sends JWT via SendGrid and validates with Postgres" — no. - **No innovation theater.** Do not fabricate differentiation or novelty language where the product is a competent execution of existing patterns. "This is a well-known shape done well" is honest and better than invented novelty. Only add an Innovation or Differentiation section when Discovery surfaced genuinely novel aspects worth naming. +- **Personas, when used, are research-grounded or marked illustrative.** Named, vivid personas force concrete thinking (especially for consumer products) but invented detail is *persona theater* — false specificity that the team then builds for. Tag composite personas `[ILLUSTRATIVE — composite from segment data, not specific research]` until grounded. Personas must drive decisions ("we built X because Maya needs Y"); if you can swap names and nothing changes, the persona is not doing work. Two to four personas max. - **Measurable where it sharpens the requirement.** Replace subjective adjectives (fast, easy, scalable, intuitive) with measurable criteria where the measurement matters. No SMART scoring ceremony, no per-FR 1-5 ratings — judgment, not ritual. - **Traceability where the chain matters.** When an FR exists *because of* a specific success criterion or a specific user journey, name the link inline. Skip full traceability matrices. - **Domain awareness.** When the domain is regulated, compliance requirements appear in the PRD — not deferred to architecture. Healthcare → HIPAA. Fintech → PCI-DSS, AML/KYC, SOX. Govtech → NIST, Section 508 / WCAG 2.1 AA, FedRAMP. E-commerce → PCI-DSS for payments. Detect at Discovery, enforce at Finalize. @@ -85,20 +86,20 @@ Patterns that hold the PRD together across every shape — hobby to enterprise. ## Constraints -- **Persistence is real-time.** Once Create intent is confirmed, the workspace (run folder, `prd.md` skeleton with `status: draft`, `decision-log.md`) exists on disk and the user knows the path. -- **File roles.** `decision-log.md` is canonical memory and audit trail — every decision, change, and override recorded as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs downstream (architecture, UX, solution design) or earned a place but does not fit the PRD shape (rejected alternatives, options matrices, sizing data, deep technical constraints). When the user volunteers technical-how detail, capture it to the addendum in real time — *"I'll capture that in addendum.md so the architecture pass picks it up."* Audit and override information never goes there. -- **Continuity across sessions.** If a prior in-progress draft for this project exists in `{workflow.output_dir}`, the user is offered to resume. +- **Persistence is real-time.** Once Create intent is confirmed, the workspace (run folder, `prd.md` skeleton, `decision-log.md`) exists on disk and the user knows the path. +- **File roles.** `decision-log.md` is canonical memory and audit trail — every decision, change, override, and version/state transition recorded as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs downstream (architecture, UX, solution design) or earned a place but does not fit the PRD shape (rejected alternatives, options matrices, sizing data, deep technical constraints, competitive analysis beyond a one-line landscape pointer, operational/cost mechanics like rate-limiting strategies and compression schemes). When the user volunteers technical-how detail, capture it to the addendum in real time — *"I'll capture that in addendum.md so the architecture pass picks it up."* Audit and override information never goes there. +- **Continuity across sessions.** If a prior in-progress draft for this project exists in `{workflow.output_dir}`, the user is offered to resume. On resume, surface the open items (Open Questions, `[ASSUMPTION]` tags, `[NOTE FOR PM]` callouts) first — they orient both the user and the agent to what was deferred. - **Extract, don't ingest.** Source artifacts (brief, distillate, research, UX work, transcripts, prior PRD, validation report, project-context, web results) never enter the parent conversation wholesale. Whenever a source document is consulted — Discovery setup, Update/Validate orientation, Finalize input reconciliation — delegate to a source-extractor subagent that returns `{summary, key_decisions, open_items, conflicts_with_focus, citations: [{section, line_range, quote}]}` against the user's stated focus. Run one subagent per document in parallel when there are multiple. The parent assembles from extracts; it never re-opens the source. -- **Downstream workflows run in fresh context.** Architecture decisions, UX journey design, epic breakdowns, and ticket bodies are not produced here. The PRD's job ends with a polished `prd.md` and its distillate. Each downstream workflow (UX, architecture, story creation, etc.) runs in a new session with the distillate as input — this skill never invokes them. +- **Downstream workflows run in fresh context.** Architecture decisions, UX journey design, epic breakdowns, and ticket bodies are not produced here. The PRD's job ends with a polished `prd.md` (and optional `addendum.md`). Each downstream workflow (UX, architecture, story creation, etc.) runs in a new session and source-extracts the slice it needs from `prd.md` directly — this skill never invokes them and produces no separate handoff artifact. - **Adapt the shape; do not impose a template.** The template asset is a menu. Hobby PRDs are short. Enterprise PRDs include stakeholder, risk, compliance, ROI, and operational sections. Use Discovery to read the situation and shape accordingly. ## Finalize 1. Decision log audit + addendum review: walk `decision-log.md` with the user and account for each meaningful entry — captured in the PRD, captured in `addendum.md` (see `## Constraints` for what belongs there), or set aside as process noise. -2. Input reconciliation: fan out one source-extractor subagent per input the user supplied (brief, distillate, research, brainstorming, prior PRD, project-context), each handed the current `prd.md` + `addendum.md` to compare against, each returning `{coverage, gaps, soft_ideas_not_landed}`. Aggregate and present the union — especially soft or qualitative ideas (tone, philosophy, interaction feel, brand voice) that the feature-and-FR shape silently drops. Ask whether any should be incorporated before polish. This must happen before the polish pass — once polish runs, additions become edits. -3. Discipline pass: re-read `prd.md` against `## PRD Discipline`. Verify Glossary terms are used identically throughout; features are grouped with their FRs nested; FRs are capabilities not implementation; every inline `[ASSUMPTION]` appears in the Assumptions Index; Non-Goals are explicit; counter-metrics are named when metrics exist; domain and project-type sections are present and right-sized; no innovation theater snuck in. -4. Polish: apply each entry in `{workflow.doc_standards}` (a `skill:`, `file:`, or plain-text directive) to `prd.md` (and `addendum.md` if it exists). Run passes as parallel subagents - apply all doc standards to `prd.md` first, then apply all doc standards to `addendum.md` so we present a high quality draft for the user to review and finalize. -5. Distillate: this is the handoff artifact for every downstream BMad workflow. Frame why it matters and invoke `bmad-distillator` with `source_documents=[prd.md, addendum.md if produced]`, `downstream_consumer="UX design, architecture, and story creation"`, `output_path={doc_workspace}/distillate.md`. If `bmad-distillator` is not installed, skip distillate generation entirely — do not attempt an inline alternative. Include `"distillate": "skipped — bmad-distillator not installed"` in the final JSON block and tell the user to install it. -6. External handoffs: execute each entry in `{workflow.external_handoffs}` to route artifacts beyond local files (Confluence, Notion, ticket systems, etc.) — each directive names the MCP tool and the fields it needs. Invoke the tool, capture any URLs or IDs returned, and surface them in the user message. If a named tool is unavailable, skip that handoff and flag it (graceful degradation, same pattern as missing `bmad-distillator`); local files always exist regardless. -7. Tell the user it is ready. Invoke the `bmad-help` skill to surface what next steps you can suggest they do in the bmad method ecosystem based on what they have set up and available, and share the paths to the PRD, addendum, distillate, decision log, any external destinations (URLs returned from handoffs), and any validation report. +2. Input reconciliation: fan out one source-extractor subagent per input the user supplied (brief, research, brainstorming, prior PRD, project-context), each handed the current `prd.md` + `addendum.md` to compare against, each returning `{coverage, gaps, soft_ideas_not_landed}`. Aggregate and present the union — especially soft or qualitative ideas (tone, philosophy, interaction feel, brand voice) that the feature-and-FR shape silently drops. Ask whether any should be incorporated before polish. This must happen before the polish pass — once polish runs, additions become edits. +3. Discipline pass: re-read `prd.md` against `## PRD Discipline`. Verify Glossary terms are used identically throughout; features are grouped with their FRs nested; FRs are capabilities not implementation; every inline `[ASSUMPTION]` appears in the Assumptions Index; Non-Goals are explicit; counter-metrics are named when metrics exist; domain and project-type sections are present and right-sized; no innovation theater snuck in; any personas are research-grounded or marked `[ILLUSTRATIVE]`. +4. Open-items review: count Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts. Summarize the totals to the user (*"This PRD ships with 14 Open Questions, 28 assumptions, and 3 PM notes"*). Walk them by category. For each, ask: resolve now, accept-and-ship (with a one-line rationale logged to `decision-log.md`), or escalate to a stakeholder. Treat high density relative to the agreed stakes as a red flag — a hobby PRD with five open items is fine; an enterprise initiative or regulated submission with twenty unresolved is not, and downstream UX/architecture/story work built on that count propagates ambiguity into stories. Surface the flag explicitly before continuing. +5. Polish: apply each entry in `{workflow.doc_standards}` (a `skill:`, `file:`, or plain-text directive) to `prd.md` (and `addendum.md` if it exists). Run passes as parallel subagents — apply all doc standards to `prd.md` first, then to `addendum.md`. +6. External handoffs: execute each entry in `{workflow.external_handoffs}` to route artifacts beyond local files (Confluence, Notion, ticket systems, etc.) — each directive names the MCP tool and the fields it needs. Invoke the tool, capture any URLs or IDs returned, and surface them in the user message. If a named tool is unavailable, skip that handoff and flag it (graceful degradation); local files always exist regardless. +7. Record finalization to `decision-log.md` (e.g., `## Finalized — {date}` with the agreed version label, any open items accepted at ship, and the locations of external destinations). Tell the user it is ready. Invoke the `bmad-help` skill to surface next steps in the BMad ecosystem based on what is set up and available; share the paths to the PRD, addendum, decision log, external destinations (URLs returned from handoffs), and any validation report. Remind the user that downstream workflows (UX, architecture, story creation) run in fresh sessions and source-extract from `prd.md` directly — there is no separate handoff artifact. 8. Run `{workflow.on_complete}` if non-empty. Treat a string scalar as a single instruction and an array as a sequence of instructions executed in order. 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 b24a4f5e6..0923257fc 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,6 @@ 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", - "distillate": "{doc_workspace}/distillate.md", "decision_log": "{doc_workspace}/decision-log.md", "open_questions": [], "assumptions": [], @@ -28,8 +27,6 @@ Every headless run ends with one of these payloads. Omit keys for artifacts not } ``` -If `bmad-distillator` is unavailable, set `"distillate": "skipped — bmad-distillator not installed"`. - ## Update ```json @@ -38,15 +35,12 @@ If `bmad-distillator` is unavailable, set `"distillate": "skipped — bmad-disti "intent": "update", "prd": "{doc_workspace}/prd.md", "decision_log": "{doc_workspace}/decision-log.md", - "distillate": "{doc_workspace}/distillate.md", "changes_summary": "1-3 sentences describing what changed and why", "conflicts_with_prior_decisions": [], "open_questions": [] } ``` -Use `"distillate": "stale"` if the regenerate step was skipped because `bmad-distillator` is unavailable. - ## Validate ```json 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 cfb52e144..6efa2944b 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 @@ -9,7 +9,6 @@ This is a menu of sections the facilitator picks from based on what the product, ```markdown --- title: {Product Name} -status: draft created: {YYYY-MM-DD} updated: {YYYY-MM-DD} --- 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 b922d1e3f..e42b3fa32 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml @@ -43,9 +43,8 @@ on_complete = "" # to enforce a different structure (e.g. regulated-industry, internal-tool, investor-input). prd_template = "assets/prd-template.md" -# Run folder location. The PRD, optional addendum, optional distillate, -# decision log, and optional validation report all land inside -# `{output_dir}/{output_folder_name}/`. +# 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}" @@ -96,6 +95,6 @@ external_sources = [] # # 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 distillate to Notion via notion:create_page (database_id='abc123', title='PRD: '+{project_name})." +# "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 = [] From 3787e386624c5ff5eacf627d0e0c602104373512 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Mon, 11 May 2026 18:46:07 -0500 Subject: [PATCH 4/7] feat(bmad-prd): outcome-driven trim, swappable validation checklist, HTML report SKILL.md trim (4.7K -> ~3.2K tokens, 124 -> 93 lines): - Cut anchor enumerations (HIPAA/PCI/NIST list, API/Mobile/Web list, hobby->regulated list, "fast/easy/scalable/intuitive", input enumerations, etc.) the LLM already knows - Cut derivable reasoning (synonyms-cause-drift explanation, hobby-vs-enterprise examples, etc.) - Cut good/bad examples that anchor LLM attention (password/SendGrid example, persona quote, "let me also add this nearby thing") - Drop SMART-ceremony language from Measurable bullet (keep judgment-not-ritual; SMART principles fine) Progressive disclosure to references/: - Headless mode rules + JSON minimal example moved to references/headless.md (loaded only when invoked headless) - On Activation step 6 gates mode detection: headless -> read references/headless.md and follow Swappable validation checklist: - New assets/prd-validation-checklist.md (15 items: Quality / Discipline / Structural / Stakes-gated, each one line) - New customize.toml field validation_checklist (override per org) - Used by Validate intent AND Finalize Step 3 -- same subagent, same checklist, two moments - Replaces bmad-validate-prd's 13-step micro-file architecture; kept the valuable check dimensions (density, measurability, traceability, implementation leakage, etc.) and dropped the ceremony HTML validation report: - New scripts/render-validation-html.py (PEP 723, stdlib only, ~175 lines) renders structured findings JSON into a styled HTML report with pass/warn/fail grade, inline SVG score bar, category grouping - New assets/validation-report-template.html (inline CSS, native
, no JS, no external deps) -- swappable via customize.toml validation_report_template - New references/validation-render.md documents the subagent output contract and renderer invocation; loaded only when validate flow runs - Auto-opens browser on interactive runs; headless skips the open Mode flow consistency: - Create and Update both now explicitly "proceed to ## Finalize" - Validate / analyze is standalone -- explicit "does NOT enter ## Finalize"; renderer auto-opens the HTML - analyze is a synonym for validate; intent detection routes both - Update mode no longer has its own light-close validation step (Finalize Step 3 covers it) --- .../2-plan-workflows/bmad-prd/SKILL.md | 101 ++++----- .../assets/prd-validation-checklist.md | 30 +++ .../assets/validation-report-template.html | 190 +++++++++++++++++ .../2-plan-workflows/bmad-prd/customize.toml | 13 ++ .../bmad-prd/references/headless.md | 24 +++ .../bmad-prd/references/validation-render.md | 60 ++++++ .../scripts/render-validation-html.py | 198 ++++++++++++++++++ 7 files changed, 559 insertions(+), 57 deletions(-) create mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-validation-checklist.md create mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/assets/validation-report-template.html create mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/references/headless.md create mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/references/validation-render.md create mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/scripts/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 54c64205f..de511fc76 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, or validating a PRD. +description: Create, update, validate, or analyze a PRD. Use when the user wants help producing, editing, validating, or analyzing a PRD. --- # BMad PRD @@ -8,98 +8,85 @@ description: Create, update, or validate a PRD. Use when the user wants help pro You are an expert PM facilitator. The user is a PM; 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`. -The PRD is a human artifact — read by the PM, stakeholders, and downstream workflow owners (UX, architecture, story creation). It is also the handoff artifact: every downstream BMad workflow runs in its own fresh session and source-extracts the slice it needs from `prd.md` (see `## Constraints` → Extract, don't ingest). This skill never invokes them. +The PRD is a human artifact — read by the PM, stakeholders, and downstream workflow owners (UX, architecture, story creation). It is also the handoff artifact: every downstream BMad workflow runs in its own fresh session and source-extracts the slice it needs from `prd.md`. ## 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. 2. Execute each entry in `{workflow.activation_steps_prepend}` in order. -3. Treat every entry in `{workflow.persistent_facts}` as foundational context for the rest of the run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim. -4. Note `{workflow.external_sources}` as a registry of external systems available for consultation when the conversation surfaces a relevant need — knowledge bases, internal MCP tools, reference systems. Do not query preemptively; consult each only when its directive matches the moment. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap when relevant. +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. Greet `{user_name}` in `{communication_language}`. Detect intent (create / update / validate). If interactive and intent is unclear, ask; for headless behavior see `## Headless Mode`. +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. 7. Execute each entry in `{workflow.activation_steps_append}` in order. ## Intent Operating Modes -**Create.** A PRD the user is proud of, drawn out through real conversation. Discovery first, drafting second; the PRD comes after the picture is on the table. Treat `{workflow.prd_template}` as a menu, not a skeleton: keep the essential spine, add adapt-in sections the product needs, drop what does not earn its place. 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`, not frontmatter. For Update and Validate, `{doc_workspace}` is the existing folder of the PRD being targeted. +**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`. -**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 (brief, research, prior UX, validation report) — then run the `## Discovery` posture against the change signal (a patch applied without context becomes drift). Surface conflicts with prior decisions before changing. Headless override: log the reversal to `decision-log.md`, then apply; halt `blocked` if intent is ambiguous. If the change is fundamental, offer Create instead of patching. +**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`. -**Validate.** Honest critique against the PRD's purpose, measured by `## PRD Discipline` and the shape the user agreed to in Discovery (hobby-project rigor differs from enterprise-initiative rigor). Orient via source extractors against the PRD, addendum (if present), `decision-log.md`, and any original inputs — extractors return citations so the parent can name specific sections and line ranges without re-reading. Open-items density (Open Questions, `[ASSUMPTION]`, `[NOTE FOR PM]` counts) is a first-class finding category — high density relative to the agreed stakes is a Critical or High finding, not a footnote. Surface findings inline; caveat what cannot be evaluated. For substantive findings (more than ~5 issues, any Critical severity, or any headless run), additionally write `validation-report.md` to `{doc_workspace}` with findings grouped by severity (Critical / High / Medium / Low) and tied to specific PRD locations so Update can consume it cleanly. Always offer to roll findings into an Update, even in headless mode — include `"offer_to_update": true` in the JSON status block. - -## Headless Mode - -When invoked headless, 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. 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: - -```json -{ - "status": "complete", - "intent": "validate", - "validation_report": "{doc_workspace}/validation-report.md", - "offer_to_update": true -} -``` +**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 + HTML report per `references/validation-render.md`. Always offer to roll findings into an Update. ## Discovery -Open with space for the full picture: invite a brain dump and ask up front for any source material the user already has — product brief (or its distillate), research, UX work already done, brainstorming, prior PRD, transcripts, project-context. Read what exists first; ask only what is missing. After the dump, a simple "anything else?" often surfaces what they almost forgot. +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: -- **Stakes.** Hobby project, internal utility feature, team initiative, enterprise program, regulated submission, public launch. Calibrates rigor, section depth, and which adapt-in clusters apply. -- **Audience.** Just the user, their team, cross-functional stakeholders, executive committee, regulators, external customers. Drives tone, evidence requirements, and approval sections. -- **Existing inputs.** A brief? Research? UX work already done with user journeys? Architectural constraints from an infra team? Existing artifacts mean those parts of the PRD reference, not relitigate. If UX exists and describes journeys, the PRD points at it; it does not duplicate. When project-context, prior PRDs, or existing UX/architecture are present, this is brownfield territory — frame Discovery around what is new or changing, not around what the product already is. -- **Downstream depth.** Is this PRD the whole spec for a small build, or the top of a chain through UX → architecture → epics → stories? The chain length affects how much the PRD encodes vs. what it defers to downstream skills. +- **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. -**Right-skill check.** Once the situation is read, honestly sanity-check that PRD is the best tool for what the user actually needs. 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** (mechanic-driven, player-experience-focused) → suggest the `bmad-gds` (game-dev-studio) module for Game Design Document (GDD) and game planning. PRD shape is wrong for games. -- **Small scope + user wants a captured artifact** (1-2 stories of change to an existing codebase, a small feature, a focused tweak — and the user wants a single doc to point at) → stay here and produce an *all-inclusive document*: lean §1-§6 plus inline Stories via the adapt-in Stories cluster. One or two pages, single source of truth, replaces a separate story-workflow run for tiny work. -- **Express implementation** (small scope or clear idea, user just wants to build now — no planning chain or captured artifact needed) → suggest `bmad-quick-dev` — takes idea or intent input and implements right away. True express track, no PRD/UX/architecture stages. +- **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 (for posterity, clarity, single-source-of-truth artifact), proceed with the right-sized version. +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 where assumptions are unexamined, where capabilities are conflated with implementation, where terms drift across the PRD, where scope creeps without a Non-Goal to push back, where a downstream reader would have to guess. Drill into specifics only after the broad shape is on the table; premature granular questions interrupt the dump and miss the room. Suggest research (web, competitive, market, domain compliance) only when the stakes warrant it. +Coach, do not quiz. Push hardest where PRD Discipline is at risk — unexamined assumptions, capability-vs-implementation confusion, term drift, silent scope creep, ambiguity for downstream readers. Drill into specifics only after the broad shape is on the table; premature granular questions interrupt the dump. Suggest research only when the stakes warrant it. ## PRD Discipline -Patterns that hold the PRD together across every shape — hobby to enterprise. +Patterns that hold the PRD together across every shape. -- **Information density.** Every sentence carries weight. Cut filler. Direct over hedged. Density scales with stakes — a hobby PRD can breathe more; an enterprise PRD must be tight. -- **Glossary-anchored vocabulary.** Every domain noun is defined once and used identically thereafter. Synonyms produce drift — downstream workflows, agents, and future-you all suffer when the same thing is called by two names. +- **Information density.** Every sentence carries weight; density scales with stakes. +- **Glossary-anchored vocabulary.** Every domain noun is defined once and used identically thereafter. Synonyms produce drift. - **Self-contained sections.** Any section should make sense pulled out alone. Cross-references go through Glossary terms, not "see above" prose. -- **Features grouped, FRs nested.** §5 organizes by feature, not by a flat FR list. Each feature has a behavioral description, then its Functional Requirements listed under it (numbered globally so downstream artifacts have stable IDs), then any feature-specific NFRs and notes. Cross-cutting NFRs live in their own section. -- **Capabilities, not implementation.** FRs describe what users (or systems) can do, not how. No technology names, library choices, or architecture decisions. "Users can reset their password via email link" — yes. "System sends JWT via SendGrid and validates with Postgres" — no. -- **No innovation theater.** Do not fabricate differentiation or novelty language where the product is a competent execution of existing patterns. "This is a well-known shape done well" is honest and better than invented novelty. Only add an Innovation or Differentiation section when Discovery surfaced genuinely novel aspects worth naming. -- **Personas, when used, are research-grounded or marked illustrative.** Named, vivid personas force concrete thinking (especially for consumer products) but invented detail is *persona theater* — false specificity that the team then builds for. Tag composite personas `[ILLUSTRATIVE — composite from segment data, not specific research]` until grounded. Personas must drive decisions ("we built X because Maya needs Y"); if you can swap names and nothing changes, the persona is not doing work. Two to four personas max. -- **Measurable where it sharpens the requirement.** Replace subjective adjectives (fast, easy, scalable, intuitive) with measurable criteria where the measurement matters. No SMART scoring ceremony, no per-FR 1-5 ratings — judgment, not ritual. -- **Traceability where the chain matters.** When an FR exists *because of* a specific success criterion or a specific user journey, name the link inline. Skip full traceability matrices. -- **Domain awareness.** When the domain is regulated, compliance requirements appear in the PRD — not deferred to architecture. Healthcare → HIPAA. Fintech → PCI-DSS, AML/KYC, SOX. Govtech → NIST, Section 508 / WCAG 2.1 AA, FedRAMP. E-commerce → PCI-DSS for payments. Detect at Discovery, enforce at Finalize. -- **Project-type awareness.** Different products need different sections. API/service → API contracts, versioning, performance budgets. Mobile → device permissions, offline behavior, OS targets. Web → accessibility, browser support. Embedded → hardware constraints, deployment topology. Library → public surface, dependency policy. The template's adapt-in menu lists these clusters. -- **Non-Goals explicit.** A short Non-Goals (Explicit) section does outsized work for downstream readers and workflows. It prevents the "let me also add this nearby thing" failure mode. Inline `[NON-GOAL for MVP]` and `[v2 — out of MVP]` callouts where they would otherwise be silently assumed. -- **Never silently de-scope.** Requirements the user explicitly included in input documents (brief, research, prior PRD) do not drop out of scope without an explicit ask. When deferral seems warranted, surface it: *"I'd recommend deferring X because [reason]. Keep it in, or move it out?"* Same gate for phasing the user did not request — propose, do not impose. +- **Features grouped, FRs nested.** Each feature opens with a behavioral description, then nests its Functional Requirements (numbered globally for stable downstream IDs), then optional feature-specific NFRs. Cross-cutting NFRs live in their own section. +- **Capabilities, not implementation.** FRs describe what users (or systems) can do, not how — no technology names, library choices, or architecture decisions. +- **No innovation theater.** Do not fabricate differentiation or novelty where the product is a competent execution of existing patterns. Add an Innovation or 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 then builds for. Personas must drive decisions; if you can swap names and nothing changes, the persona is not doing work. Two to four max. +- **Measurable where it sharpens the requirement.** Replace subjective adjectives with measurable criteria where the measurement matters — judgment, not ritual. +- **Traceability where the chain matters.** When an FR exists *because of* a specific success criterion or user journey, name the link inline. Skip full traceability matrices. +- **Domain awareness.** When the domain has regulatory or compliance constraints, surface them in the PRD — not deferred to architecture. Detect at Discovery, enforce at Finalize. +- **Project-type awareness.** Match section depth and adapt-in clusters to the project type — the template's adapt-in menu names the standard clusters. +- **Non-Goals explicit.** A Non-Goals (Explicit) section does outsized work for downstream readers; pair it with inline `[NON-GOAL for MVP]` and `[v2 — out of MVP]` callouts where omissions would otherwise be silently assumed. +- **Never silently de-scope.** Requirements the user explicitly included do not drop without an explicit ask. Same gate for phasing the user did not request — propose, do not impose. - **Counter-metrics named.** Metrics not to optimize are as load-bearing as the ones to optimize. Name them when Success Metrics is in the PRD. -- **Assumptions visible.** Inferences made without direct user confirmation are tagged `[ASSUMPTION: ...]` inline and indexed at the end so downstream readers can flag them rather than absorbing them as fact. -- **`[NOTE FOR PM]` callouts** at decision points the user deferred or left tension on — surface them so the next session or the next reviewer can revisit. -- **Right-size to purpose.** A hobby project does not need investor-grade rigor. A regulated submission does. Length, depth, and which adapt-in clusters apply all scale with stakes. +- **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. +- **Right-size to purpose.** Length, depth, and adapt-in clusters scale with stakes. ## Constraints - **Persistence is real-time.** Once Create intent is confirmed, the workspace (run folder, `prd.md` skeleton, `decision-log.md`) exists on disk and the user knows the path. -- **File roles.** `decision-log.md` is canonical memory and audit trail — every decision, change, override, and version/state transition recorded as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs downstream (architecture, UX, solution design) or earned a place but does not fit the PRD shape (rejected alternatives, options matrices, sizing data, deep technical constraints, competitive analysis beyond a one-line landscape pointer, operational/cost mechanics like rate-limiting strategies and compression schemes). When the user volunteers technical-how detail, capture it to the addendum in real time — *"I'll capture that in addendum.md so the architecture pass picks it up."* Audit and override information never goes there. +- **File roles.** `decision-log.md` is canonical memory and audit trail — every decision, change, override, and version/state transition recorded as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs downstream or earned a place but does not fit the PRD shape (rejected alternatives, options matrices, deep technical detail, ops/cost mechanics, deep competitive analysis). When the user volunteers technical-how detail, capture it to addendum in real time. Audit and override information never goes there. - **Continuity across sessions.** If a prior in-progress draft for this project exists in `{workflow.output_dir}`, the user is offered to resume. On resume, surface the open items (Open Questions, `[ASSUMPTION]` tags, `[NOTE FOR PM]` callouts) first — they orient both the user and the agent to what was deferred. -- **Extract, don't ingest.** Source artifacts (brief, distillate, research, UX work, transcripts, prior PRD, validation report, project-context, web results) never enter the parent conversation wholesale. Whenever a source document is consulted — Discovery setup, Update/Validate orientation, Finalize input reconciliation — delegate to a source-extractor subagent that returns `{summary, key_decisions, open_items, conflicts_with_focus, citations: [{section, line_range, quote}]}` against the user's stated focus. Run one subagent per document in parallel when there are multiple. The parent assembles from extracts; it never re-opens the source. -- **Downstream workflows run in fresh context.** Architecture decisions, UX journey design, epic breakdowns, and ticket bodies are not produced here. The PRD's job ends with a polished `prd.md` (and optional `addendum.md`). Each downstream workflow (UX, architecture, story creation, etc.) runs in a new session and source-extracts the slice it needs from `prd.md` directly — this skill never invokes them and produces no separate handoff artifact. -- **Adapt the shape; do not impose a template.** The template asset is a menu. Hobby PRDs are short. Enterprise PRDs include stakeholder, risk, compliance, ROI, and operational sections. Use Discovery to read the situation and shape accordingly. +- **Extract, don't ingest.** Source artifacts never enter the parent conversation wholesale. Whenever a source document is consulted — Discovery setup, Update/Validate orientation, Finalize input reconciliation — delegate to a source-extractor subagent that returns `{summary, key_decisions, open_items, conflicts_with_focus, citations: [{section, line_range, quote}]}` against the user's stated focus. Run one subagent per document in parallel when there are multiple. The parent assembles from extracts; it never re-opens the source. +- **Downstream workflows run in fresh context.** The PRD's job ends with a polished `prd.md` (and optional `addendum.md`). Each downstream workflow runs in a new session and source-extracts the slice it needs from `prd.md` directly — this skill never invokes them and produces no separate handoff artifact. +- **Adapt the shape; do not impose a template.** The template asset is a menu — use Discovery to read the situation and shape accordingly. ## Finalize 1. Decision log audit + addendum review: walk `decision-log.md` with the user and account for each meaningful entry — captured in the PRD, captured in `addendum.md` (see `## Constraints` for what belongs there), or set aside as process noise. -2. Input reconciliation: fan out one source-extractor subagent per input the user supplied (brief, research, brainstorming, prior PRD, project-context), each handed the current `prd.md` + `addendum.md` to compare against, each returning `{coverage, gaps, soft_ideas_not_landed}`. Aggregate and present the union — especially soft or qualitative ideas (tone, philosophy, interaction feel, brand voice) that the feature-and-FR shape silently drops. Ask whether any should be incorporated before polish. This must happen before the polish pass — once polish runs, additions become edits. -3. Discipline pass: re-read `prd.md` against `## PRD Discipline`. Verify Glossary terms are used identically throughout; features are grouped with their FRs nested; FRs are capabilities not implementation; every inline `[ASSUMPTION]` appears in the Assumptions Index; Non-Goals are explicit; counter-metrics are named when metrics exist; domain and project-type sections are present and right-sized; no innovation theater snuck in; any personas are research-grounded or marked `[ILLUSTRATIVE]`. -4. Open-items review: count Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts. Summarize the totals to the user (*"This PRD ships with 14 Open Questions, 28 assumptions, and 3 PM notes"*). Walk them by category. For each, ask: resolve now, accept-and-ship (with a one-line rationale logged to `decision-log.md`), or escalate to a stakeholder. Treat high density relative to the agreed stakes as a red flag — a hobby PRD with five open items is fine; an enterprise initiative or regulated submission with twenty unresolved is not, and downstream UX/architecture/story work built on that count propagates ambiguity into stories. Surface the flag explicitly before continuing. +2. Input reconciliation: fan out one source-extractor subagent per user-supplied input, each handed the current `prd.md` + `addendum.md` to compare against, returning `{coverage, gaps, soft_ideas_not_landed}`. Aggregate and present — especially soft or qualitative ideas (tone, voice, feel) the feature-and-FR shape silently drops. Ask whether any should be incorporated. Must happen before polish. +3. Discipline pass: spawn the validator subagent against `prd.md` with `{workflow.validation_checklist}`; produce findings + HTML report per `references/validation-render.md`. Surface failures and warnings conversationally; resolve before polish. +4. Open-items review: count Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts. Summarize totals to the user and walk them by category. For each: resolve now, accept-and-ship (log rationale to `decision-log.md`), or escalate. Flag high density relative to the agreed stakes as a red flag before continuing. 5. Polish: apply each entry in `{workflow.doc_standards}` (a `skill:`, `file:`, or plain-text directive) to `prd.md` (and `addendum.md` if it exists). Run passes as parallel subagents — apply all doc standards to `prd.md` first, then to `addendum.md`. -6. External handoffs: execute each entry in `{workflow.external_handoffs}` to route artifacts beyond local files (Confluence, Notion, ticket systems, etc.) — each directive names the MCP tool and the fields it needs. Invoke the tool, capture any URLs or IDs returned, and surface them in the user message. If a named tool is unavailable, skip that handoff and flag it (graceful degradation); local files always exist regardless. -7. Record finalization to `decision-log.md` (e.g., `## Finalized — {date}` with the agreed version label, any open items accepted at ship, and the locations of external destinations). Tell the user it is ready. Invoke the `bmad-help` skill to surface next steps in the BMad ecosystem based on what is set up and available; share the paths to the PRD, addendum, decision log, external destinations (URLs returned from handoffs), and any validation report. Remind the user that downstream workflows (UX, architecture, story creation) run in fresh sessions and source-extract from `prd.md` directly — there is no separate handoff artifact. +6. External handoffs: execute each entry in `{workflow.external_handoffs}` — each directive names the MCP tool and the fields it needs. Invoke, capture any URLs or IDs returned, surface them. If a named tool is unavailable, skip and flag (graceful degradation); local files always exist. +7. Record finalization to `decision-log.md` (version label, accepted-at-ship open items, external destinations). Tell the user it is ready, share artifact paths (PRD, addendum, decision log, external destinations, validation report). Invoke the `bmad-help` skill to surface BMad-ecosystem next steps. 8. Run `{workflow.on_complete}` if non-empty. Treat a string scalar as a single instruction and an array as a sequence of instructions executed in order. 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 new file mode 100644 index 000000000..a6b3cbef9 --- /dev/null +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-validation-checklist.md @@ -0,0 +1,30 @@ +# PRD Validation Checklist + +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. + +## Quality + +- **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-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. + +## Discipline + +- **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. + +## 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-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. + +## Stakes-gated + +- **STK-1. Required sections.** The PRD includes the sections the agreed stakes and product type warrant. 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 new file mode 100644 index 000000000..1e3136607 --- /dev/null +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/validation-report-template.html @@ -0,0 +1,190 @@ + + + + +PRD Validation: $prd_name + + + +
+
+
+

$prd_name — Validation Report

+
$prd_path
+
+
$grade
+
+ +
$overall_synthesis
+ +
+
$score_svg
+
+ $passed pass + $warned warn + $failed fail + $na n/a + $total items checked +
+
+ + $categories_html + +
+
+ Checklist: $checklist_path + Generated: $timestamp +
+
+
+ + 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 e42b3fa32..534bf7de4 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml @@ -43,6 +43,19 @@ on_complete = "" # to enforce a different structure (e.g. regulated-industry, internal-tool, investor-input). prd_template = "assets/prd-template.md" +# Validation checklist used at the Validate intent and at Finalize step 3. +# 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" + +# HTML template used to render validation findings into a styled, scannable +# report. The renderer (scripts/render-validation-html.py) substitutes +# structured findings + summary stats into this template; the template is +# fully overridable to match org branding. The default uses inline CSS, no +# external dependencies, and native HTML
for collapse — no JS. +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" 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 new file mode 100644 index 000000000..761730efc --- /dev/null +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/headless.md @@ -0,0 +1,24 @@ +# Headless Mode + +Load this file when bmad-prd is invoked headless (no interactive user). Follow it for the whole run. + +## 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. + +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: + +```json +{ + "status": "complete", + "intent": "validate", + "validation_report": "{doc_workspace}/validation-report.md", + "offer_to_update": true +} +``` + +## Mode-specific overrides + +**Update.** Log the reversal to `decision-log.md`, then apply. 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. 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 new file mode 100644 index 000000000..d4c7c9bb6 --- /dev/null +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/validation-render.md @@ -0,0 +1,60 @@ +# Validation Rendering + +How the validator subagent's findings become the HTML report. Loaded by the parent on any Validate or Finalize-step-3 invocation. + +## Validator subagent output contract + +The subagent walks `{workflow.validation_checklist}` against `prd.md` (and `addendum.md` if present) and writes `{doc_workspace}/validation-findings.json`: + +```json +{ + "prd_name": "Plantsona", + "prd_path": "{doc_workspace}/prd.md", + "checklist_path": "{workflow.validation_checklist}", + "timestamp": "2026-05-11T09: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", + "category": "Quality", + "title": "Measurability", + "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." + } + ] +} +``` + +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. + +## Rendering invocation + +After the subagent writes findings: + +```bash +python3 {skill-root}/scripts/render-validation-html.py \ + --findings {doc_workspace}/validation-findings.json \ + --template {workflow.validation_report_template} \ + --output {doc_workspace}/validation-report.html \ + --open +``` + +Include `--open` for interactive runs (auto-opens in default browser). Omit `--open` in headless runs. + +The script 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, groups findings by category, and substitutes into the template. Returns a one-line JSON summary on stdout: `{"output": "...", "grade": "...", "stats": {...}}`. + +## Markdown companion + +When findings include any Critical-severity item or >5 total fail/warn items, also write `{doc_workspace}/validation-report.md` — a markdown rendering of the same findings, grouped by severity, with PRD line references. Update mode consumes the markdown form cleanly when rolling findings into a revision. diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/scripts/render-validation-html.py b/src/bmm-skills/2-plan-workflows/bmad-prd/scripts/render-validation-html.py new file mode 100644 index 000000000..e65c97ab9 --- /dev/null +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/scripts/render-validation-html.py @@ -0,0 +1,198 @@ +#!/usr/bin/env python3 +# /// script +# requires-python = ">=3.10" +# /// +"""Render a PRD validation findings JSON into a styled HTML report. + +Reads structured findings produced by the validator subagent, groups them by +category (explicit `category` field, else derived from ID prefix), computes a +pass/warn/fail summary and grade, substitutes into the configured HTML +template, and optionally opens the result in the default browser. +""" + +import argparse +import html +import json +import string +import sys +import webbrowser +from datetime import datetime +from pathlib import Path + +CATEGORY_FROM_PREFIX = { + "Q": "Quality", + "D": "Discipline", + "S": "Structural integrity", + "STK": "Stakes-gated", + "M": "Mechanical", +} + +CATEGORY_ORDER = ["Quality", "Discipline", "Structural integrity", "Stakes-gated", "Mechanical"] + + +def category_for(finding: dict) -> str: + explicit = finding.get("category") + if explicit: + return explicit + fid = finding.get("id", "") + prefix = fid.split("-", 1)[0] if "-" in fid else fid + return CATEGORY_FROM_PREFIX.get(prefix, prefix or "Other") + + +def compute_stats(findings: list[dict]) -> dict: + total = len(findings) + by_status = {"pass": 0, "warn": 0, "fail": 0, "n/a": 0} + failed_critical = 0 + failed_high = 0 + for f in findings: + status = f.get("status", "n/a") + if status in by_status: + by_status[status] += 1 + if status == "fail": + sev = (f.get("severity") or "low").lower() + if sev == "critical": + failed_critical += 1 + elif sev == "high": + failed_high += 1 + return { + "total": total, + "passed": by_status["pass"], + "warned": by_status["warn"], + "failed": by_status["fail"], + "na": by_status["n/a"], + "failed_critical": failed_critical, + "failed_high": failed_high, + } + + +def grade_from(stats: dict) -> tuple[str, str]: + if stats["failed_critical"] > 0: + return "Poor", "grade-poor" + if stats["failed_high"] >= 1 or stats["failed"] >= 4: + return "Fair", "grade-fair" + if stats["failed"] > 0 or stats["warned"] > 2: + return "Good", "grade-good" + return "Excellent", "grade-excellent" + + +def render_score_bar(stats: dict, width: int = 480, height: int = 22) -> str: + total = max(stats["total"], 1) + p = stats["passed"] / total * width + w = stats["warned"] / total * width + f = stats["failed"] / total * width + n = stats["na"] / total * width + return ( + f'' + f'' + f'' + f'' + f'' + f"" + ) + + +def render_finding(f: dict) -> str: + status = (f.get("status") or "n/a").lower() + severity = (f.get("severity") or "low").lower() + fid = html.escape(f.get("id") or "") + title = html.escape(f.get("title") or fid) + location = html.escape(f.get("location") or "") + note = html.escape(f.get("note") or "") + fix = html.escape(f.get("suggested_fix") or "") + + status_class = "na" if status == "n/a" else status + parts = [ + f'
', + '
', + f'{status.upper()}', + f'{severity}', + f'{fid}', + f'

{title}

', + '
', + ] + if location: + parts.append(f'
Location: {location}
') + if note: + parts.append(f'
{note}
') + if fix: + parts.append(f'
Suggested fix: {fix}
') + parts.append("
") + return "\n".join(parts) + + +def render_category(name: str, findings: list[dict]) -> str: + items = "\n".join(render_finding(f) for f in findings) + name_e = html.escape(name) + return ( + f'
' + f"
" + f'

{name_e} ({len(findings)})

' + f"{items}" + f"
" + f"
" + ) + + +def main(argv: list[str]) -> int: + parser = argparse.ArgumentParser(description="Render PRD validation findings to HTML.") + parser.add_argument("--findings", required=True, help="Path to validation-findings.json") + parser.add_argument("--template", required=True, help="Path to HTML template") + parser.add_argument("--output", required=True, help="Path to write the rendered HTML") + parser.add_argument("--open", action="store_true", help="Open the rendered HTML in the default browser") + args = parser.parse_args(argv) + + findings_path = Path(args.findings) + template_path = Path(args.template) + output_path = Path(args.output) + + data = json.loads(findings_path.read_text()) + template = template_path.read_text() + + findings = data.get("findings", []) or [] + + by_cat: dict[str, list[dict]] = {} + for f in findings: + by_cat.setdefault(category_for(f), []).append(f) + + sorted_cats = sorted( + by_cat.keys(), + key=lambda c: (CATEGORY_ORDER.index(c) if c in CATEGORY_ORDER else 99, c), + ) + categories_html = "\n".join(render_category(c, by_cat[c]) for c in sorted_cats) + + stats = compute_stats(findings) + grade, grade_class = grade_from(stats) + score_svg = render_score_bar(stats) + + timestamp = data.get("timestamp") or datetime.now().isoformat(timespec="seconds") + substitutions = { + "prd_name": html.escape(str(data.get("prd_name") or "PRD")), + "prd_path": html.escape(str(data.get("prd_path") or "")), + "checklist_path": html.escape(str(data.get("checklist_path") or "")), + "timestamp": html.escape(timestamp), + "overall_synthesis": html.escape(str(data.get("overall_synthesis") or "")), + "grade": grade, + "grade_class": grade_class, + "total": str(stats["total"]), + "passed": str(stats["passed"]), + "failed": str(stats["failed"]), + "warned": str(stats["warned"]), + "na": str(stats["na"]), + "score_svg": score_svg, + "categories_html": categories_html, + } + + rendered = string.Template(template).safe_substitute(substitutions) + output_path.write_text(rendered) + + print(json.dumps({"output": str(output_path), "grade": grade, "stats": stats})) + + if args.open: + webbrowser.open(output_path.resolve().as_uri()) + + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) From 1a88f001d566329a01ff948f8fa4f6959d9fd1eb Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Tue, 12 May 2026 22:17:56 -0500 Subject: [PATCH 5/7] refactor(product-brief,bmad-prd): remove distillation from brief and PRD workflows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop bmad-distillator integration from bmad-product-brief (finalize step, update mode, headless JSON, constraints) and clean up customize.toml comments. Distillation is the wrong layer — story self-containment via epic solution design docs is the right answer for downstream context. Also commit pending bmad-prd changes: working mode selector (Express vs Facilitative), open-items triage into phase-blocking/resolvable/deferred buckets, persistence wording fix, and facilitation-guide reference. --- .../1-analysis/bmad-product-brief/SKILL.md | 12 ++- .../bmad-product-brief/customize.toml | 4 +- .../2-plan-workflows/bmad-prd/SKILL.md | 15 +++- .../bmad-prd/references/facilitation-guide.md | 79 +++++++++++++++++++ 4 files changed, 98 insertions(+), 12 deletions(-) create mode 100644 src/bmm-skills/2-plan-workflows/bmad-prd/references/facilitation-guide.md diff --git a/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md b/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md index 7fd7ba006..3b6cde63c 100644 --- a/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md +++ b/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md @@ -25,7 +25,7 @@ Briefs produced here are honest, right-sized to purpose, and built for what come **Create.** A brief the user is proud of, that meets their needs, drawn out through real conversation — do not assume: instead converse and understand, and then help craft the best product brief for their needs. Begin in `## Discovery` before drafting; the brief comes after the picture is on the table. Shape follows the product and need. Treat `{workflow.brief_template}` as a starting structure, not a contract: drop sections that do not earn their place, add sections the product needs, reorder freely - create sections for specialized domains or concerns also as needed. The brief serves the product's story, not the template's shape. Bind `{doc_workspace}` to a fresh folder at `{workflow.output_dir}/{workflow.output_folder_name}/` and write `brief.md` there with YAML frontmatter (title, status, created, updated). For Update and Validate, `{doc_workspace}` is the existing folder of the brief being targeted. -**Update.** Reconcile an existing brief with a change signal. Before proposing changes, read the brief, addendum, `decision-log.md`, and original inputs — and run the `## Discovery` posture against the change signal (a patch applied without context becomes drift). Surface conflicts with prior decisions before changing. Headless override: log the reversal to `decision-log.md`, then apply; halt `blocked` if intent is ambiguous. If the change is fundamental, offer Create instead of patching. Regenerate `distillate.md` via `bmad-distillator` if it exists; if the skill is unavailable, flag the distillate as stale in the JSON output. +**Update.** Reconcile an existing brief with a change signal. Before proposing changes, read the brief, addendum, `decision-log.md`, and original inputs — and run the `## Discovery` posture against the change signal (a patch applied without context becomes drift). Surface conflicts with prior decisions before changing. Headless override: log the reversal to `decision-log.md`, then apply; halt `blocked` if intent is ambiguous. If the change is fundamental, offer Create instead of patching. **Validate.** Honest critique against the brief's own purpose. Read the brief, the addendum if present, `decision-log.md`, and any original inputs first — a validation that ignores prior decisions, rejected ideas, or context the user supplied is shallow. Cite specific lines. Caveat what cannot be evaluated. Return inline — no separate file unless asked. Always offer to roll findings into an Update, even in headless mode — include `"offer_to_update": true` in the JSON status block. @@ -39,7 +39,6 @@ When invoked headless, do not ask. Complete the intent using what is provided, w "intent": "create", "brief": "{doc_workspace}/brief.md", "addendum": "{doc_workspace}/addendum.md", - "distillate": "{doc_workspace}/distillate.md", "decision_log": "{doc_workspace}/decision-log.md", "open_questions": [], "external_handoffs": [ @@ -69,13 +68,12 @@ Conversationally surface what the user brings, why this brief exists, and the do - **File roles.** `decision-log.md` is canonical memory and audit trail — every decision, change, and override (including headless overrides) is recorded there as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs in a downstream document (PRD, architecture, solution design) or earned a place but does not fit the brief (rejected-alternative rationale, options-considered matrices, parked-roadmap context, technical constraints, in-depth personas, sizing data). Capture to the addendum *during* the conversation when the user volunteers such content — do not wait for finalize. Audit and override information never goes in the addendum. - **Continuity across sessions.** If a prior in-progress draft for this project exists, the user is offered to resume. - **Extract, don't ingest.** Source artifacts (provided by the user or discovered during the run — transcripts, brainstorms, research reports, code, web results, prior briefs) enter the parent conversation as relevance-filtered extracts, not loaded wholesale. Subagents do the extraction against the user's stated focus; the parent context stays lean. -- **Length and coherence.** Aim for 1-2 pages — if it is longer, the detail belongs in the addendum or distillate. Structure in service of the product; downstream consumers (PRD workflow, etc.) read this, so coherent shape matters. +- **Length and coherence.** Aim for 1-2 pages — if it is longer, the detail belongs in the addendum. Structure in service of the product; downstream consumers (PRD workflow, etc.) read this, so coherent shape matters. ## Finalize 1. Decision log audit + addendum review: the user ends this step with an explicit, shared accounting of how the meaningful contents of `decision-log.md` were handled — captured in the brief, captured in `addendum.md` (which may already hold detail captured during the conversation — see `## Constraints` for what belongs there), or set aside as process noise. 2. Polish: apply each entry in `{workflow.doc_standards}` (a `skill:`, `file:`, or plain-text directive) to `brief.md` (and `addendum.md` if it exists). Run passes as parallel subagents - apply all doc standards to `brief.md` first, then `addendum.md` so we present a high quality draft for the user to review and finalize. -3. Distillate: offer the user a lean, token-efficient distillate of the brief — frame why it matters (it becomes the primary input when downstream BMad workflows like PRD creation pull this brief in). If they want it, invoke `bmad-distillator` with `source_documents=[brief.md, addendum.md if produced]`, `downstream_consumer="PRD creation"`, `output_path={doc_workspace}/distillate.md`. If `bmad-distillator` is not installed, skip distillate generation entirely — do not attempt an inline alternative. Include `"distillate": "skipped — bmad-distillator not installed"` in the final JSON block and tell the user to install it. -4. External handoffs: execute each entry in `{workflow.external_handoffs}` to route artifacts beyond local files (Confluence, Notion, ticket systems, etc.) — each directive names the MCP tool and the fields it needs. Invoke the tool, capture any URLs or IDs returned, and surface them in the user message. If a named tool is unavailable, skip that handoff and flag it (graceful degradation, same pattern as missing `bmad-distillator`); local files always exist regardless. -5. Tell the user it is ready: local paths, external destinations (URLs returned from handoffs), distillate path. Use the `bmad-help` skill to suggest what next steps make sense in the bmad method ecosystem. -6. Run `{workflow.on_complete}` if non-empty. Treat a string scalar as a single instruction and an array as a sequence of instructions executed in order. +3. External handoffs: execute each entry in `{workflow.external_handoffs}` to route artifacts beyond local files (Confluence, Notion, ticket systems, etc.) — each directive names the MCP tool and the fields it needs. Invoke the tool, capture any URLs or IDs returned, and surface them in the user message. If a named tool is unavailable, skip that handoff and flag it; local files always exist regardless. +4. Tell the user it is ready: local paths and external destinations (URLs returned from handoffs). Use the `bmad-help` skill to suggest what next steps make sense in the bmad method ecosystem. +5. Run `{workflow.on_complete}` if non-empty. Treat a string scalar as a single instruction and an array as a sequence of instructions executed in order. diff --git a/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml b/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml index 555f661a4..757778799 100644 --- a/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml +++ b/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml @@ -39,8 +39,7 @@ on_complete = "" # to enforce a different structure (e.g. regulated-industry, investor-deck). brief_template = "assets/brief-template.md" -# Run folder location. The brief, optional addendum, and optional distillate -# all land inside `{output_dir}/{output_folder_name}/`. +# Run folder location. The brief and optional addendum land inside `{output_dir}/{output_folder_name}/`. output_dir = "{planning_artifacts}/briefs" output_folder_name = "brief-{project_name}-{date}" @@ -91,6 +90,5 @@ external_sources = [] # # Examples (set in team/user override TOML): # "After finalize, upload brief.md and addendum.md to Confluence via corp:confluence_upload (space_key='PROD', parent_page='Product Briefs', label='brief', author={user_name})." -# "Mirror the distillate to Notion via notion:create_page (database_id='abc123', title='Brief: '+{project_name})." # "Post a ready-for-review ping to Slack via corp:slack_post (channel='#product', text='New brief: '+{confluence_url})." external_handoffs = [] 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 de511fc76..19b2f9d5d 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -49,6 +49,13 @@ Surface these honestly and let the user choose; if they prefer this skill anyway Coach, do not quiz. Push hardest where PRD Discipline is at risk — unexamined assumptions, capability-vs-implementation confusion, term drift, silent scope creep, ambiguity for downstream readers. Drill into specifics only after the broad shape is on the table; premature granular questions interrupt the dump. Suggest research only when the stakes warrant it. +**Working mode.** 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`. Draft after the key sections are walked. The goal is that the PM 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 Patterns that hold the PRD together across every shape. @@ -73,7 +80,7 @@ Patterns that hold the PRD together across every shape. ## Constraints -- **Persistence is real-time.** Once Create intent is confirmed, the workspace (run folder, `prd.md` skeleton, `decision-log.md`) exists on disk and the user knows the path. +- **Persistence is near real-time.** Once Create intent is confirmed, the workspace (run folder, `prd.md` skeleton, `decision-log.md`) must be created on disk and the user let know of the path. - **File roles.** `decision-log.md` is canonical memory and audit trail — every decision, change, override, and version/state transition recorded as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs downstream or earned a place but does not fit the PRD shape (rejected alternatives, options matrices, deep technical detail, ops/cost mechanics, deep competitive analysis). When the user volunteers technical-how detail, capture it to addendum in real time. Audit and override information never goes there. - **Continuity across sessions.** If a prior in-progress draft for this project exists in `{workflow.output_dir}`, the user is offered to resume. On resume, surface the open items (Open Questions, `[ASSUMPTION]` tags, `[NOTE FOR PM]` callouts) first — they orient both the user and the agent to what was deferred. - **Extract, don't ingest.** Source artifacts never enter the parent conversation wholesale. Whenever a source document is consulted — Discovery setup, Update/Validate orientation, Finalize input reconciliation — delegate to a source-extractor subagent that returns `{summary, key_decisions, open_items, conflicts_with_focus, citations: [{section, line_range, quote}]}` against the user's stated focus. Run one subagent per document in parallel when there are multiple. The parent assembles from extracts; it never re-opens the source. @@ -85,7 +92,11 @@ Patterns that hold the PRD together across every shape. 1. Decision log audit + addendum review: walk `decision-log.md` with the user and account for each meaningful entry — captured in the PRD, captured in `addendum.md` (see `## Constraints` for what belongs there), or set aside as process noise. 2. Input reconciliation: fan out one source-extractor subagent per user-supplied input, each handed the current `prd.md` + `addendum.md` to compare against, returning `{coverage, gaps, soft_ideas_not_landed}`. Aggregate and present — especially soft or qualitative ideas (tone, voice, feel) the feature-and-FR shape silently drops. Ask whether any should be incorporated. Must happen before polish. 3. Discipline pass: spawn the validator subagent against `prd.md` with `{workflow.validation_checklist}`; produce findings + HTML report per `references/validation-render.md`. Surface failures and warnings conversationally; resolve before polish. -4. Open-items review: count Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts. Summarize totals to the user and walk them by category. For each: resolve now, accept-and-ship (log rationale to `decision-log.md`), or escalate. Flag high density relative to the agreed stakes as a red flag before continuing. +4. Open-items review: triage all Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts into three buckets before presenting anything to the user: + - **Phase-blocking** — the next BMad workflow (UX, architecture) cannot start without this decision. Surface these explicitly and conversationally, one at a time. Resolve before calling the PRD ready. + - **Resolvable now** — answerable in under a minute. Offer to close them; do not force it. + - **Safely deferred** — will surface naturally in a downstream phase (architecture, UX, post-launch) or is a v2 decision. Log to `decision-log.md` as accepted-at-draft with a one-line note on where they belong. Do not make the user walk these. + Never recite the full list. Lead with: "There are N things to decide before [next phase] can start" — then work through only those. If phase-blocking count is high relative to agreed stakes, flag it as a red flag before continuing. 5. Polish: apply each entry in `{workflow.doc_standards}` (a `skill:`, `file:`, or plain-text directive) to `prd.md` (and `addendum.md` if it exists). Run passes as parallel subagents — apply all doc standards to `prd.md` first, then to `addendum.md`. 6. External handoffs: execute each entry in `{workflow.external_handoffs}` — each directive names the MCP tool and the fields it needs. Invoke, capture any URLs or IDs returned, surface them. If a named tool is unavailable, skip and flag (graceful degradation); local files always exist. 7. Record finalization to `decision-log.md` (version label, accepted-at-ship open items, external destinations). Tell the user it is ready, share artifact paths (PRD, addendum, decision log, external destinations, validation report). Invoke the `bmad-help` skill to surface BMad-ecosystem next 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 new file mode 100644 index 000000000..e5cbb706b --- /dev/null +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/facilitation-guide.md @@ -0,0 +1,79 @@ +# 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. + +--- + +## 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 4baca1880eec1f598c5e2ebb9f3e88e32433399c Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Tue, 12 May 2026 23:21:40 -0500 Subject: [PATCH 6/7] refactor(bmad-prd): aggressive SKILL.md compression, remove LLM-obvious content --- .../2-plan-workflows/bmad-prd/SKILL.md | 65 +++++++------------ 1 file changed, 25 insertions(+), 40 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 19b2f9d5d..2a5ea213e 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -6,9 +6,7 @@ description: Create, update, validate, or analyze a PRD. Use when the user wants ## Overview -You are an expert PM facilitator. The user is a PM; 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`. - -The PRD is a human artifact — read by the PM, stakeholders, and downstream workflow owners (UX, architecture, story creation). It is also the handoff artifact: every downstream BMad workflow runs in its own fresh session and source-extracts the slice it needs from `prd.md`. +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`. ## On Activation @@ -47,57 +45,44 @@ 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 where PRD Discipline is at risk — unexamined assumptions, capability-vs-implementation confusion, term drift, silent scope creep, ambiguity for downstream readers. Drill into specifics only after the broad shape is on the table; premature granular questions interrupt the dump. Suggest research only when the stakes warrant it. +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.** 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`. Draft after the key sections are walked. The goal is that the PM 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 -Patterns that hold the PRD together across every shape. - -- **Information density.** Every sentence carries weight; density scales with stakes. -- **Glossary-anchored vocabulary.** Every domain noun is defined once and used identically thereafter. Synonyms produce drift. -- **Self-contained sections.** Any section should make sense pulled out alone. Cross-references go through Glossary terms, not "see above" prose. -- **Features grouped, FRs nested.** Each feature opens with a behavioral description, then nests its Functional Requirements (numbered globally for stable downstream IDs), then optional feature-specific NFRs. Cross-cutting NFRs live in their own section. -- **Capabilities, not implementation.** FRs describe what users (or systems) can do, not how — no technology names, library choices, or architecture decisions. -- **No innovation theater.** Do not fabricate differentiation or novelty where the product is a competent execution of existing patterns. Add an Innovation or 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 then builds for. Personas must drive decisions; if you can swap names and nothing changes, the persona is not doing work. Two to four max. -- **Measurable where it sharpens the requirement.** Replace subjective adjectives with measurable criteria where the measurement matters — judgment, not ritual. -- **Traceability where the chain matters.** When an FR exists *because of* a specific success criterion or user journey, name the link inline. Skip full traceability matrices. -- **Domain awareness.** When the domain has regulatory or compliance constraints, surface them in the PRD — not deferred to architecture. Detect at Discovery, enforce at Finalize. -- **Project-type awareness.** Match section depth and adapt-in clusters to the project type — the template's adapt-in menu names the standard clusters. -- **Non-Goals explicit.** A Non-Goals (Explicit) section does outsized work for downstream readers; pair it with inline `[NON-GOAL for MVP]` and `[v2 — out of MVP]` callouts where omissions would otherwise be silently assumed. -- **Never silently de-scope.** Requirements the user explicitly included do not drop without an explicit ask. Same gate for phasing the user did not request — propose, do not impose. -- **Counter-metrics named.** Metrics not to optimize are as load-bearing as the ones to optimize. Name them when Success Metrics is in the PRD. +- **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. +- **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. +- **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. -- **Right-size to purpose.** Length, depth, and adapt-in clusters scale with stakes. ## Constraints -- **Persistence is near real-time.** Once Create intent is confirmed, the workspace (run folder, `prd.md` skeleton, `decision-log.md`) must be created on disk and the user let know of the path. -- **File roles.** `decision-log.md` is canonical memory and audit trail — every decision, change, override, and version/state transition recorded as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs downstream or earned a place but does not fit the PRD shape (rejected alternatives, options matrices, deep technical detail, ops/cost mechanics, deep competitive analysis). When the user volunteers technical-how detail, capture it to addendum in real time. Audit and override information never goes there. -- **Continuity across sessions.** If a prior in-progress draft for this project exists in `{workflow.output_dir}`, the user is offered to resume. On resume, surface the open items (Open Questions, `[ASSUMPTION]` tags, `[NOTE FOR PM]` callouts) first — they orient both the user and the agent to what was deferred. -- **Extract, don't ingest.** Source artifacts never enter the parent conversation wholesale. Whenever a source document is consulted — Discovery setup, Update/Validate orientation, Finalize input reconciliation — delegate to a source-extractor subagent that returns `{summary, key_decisions, open_items, conflicts_with_focus, citations: [{section, line_range, quote}]}` against the user's stated focus. Run one subagent per document in parallel when there are multiple. The parent assembles from extracts; it never re-opens the source. -- **Downstream workflows run in fresh context.** The PRD's job ends with a polished `prd.md` (and optional `addendum.md`). Each downstream workflow runs in a new session and source-extracts the slice it needs from `prd.md` directly — this skill never invokes them and produces no separate handoff artifact. -- **Adapt the shape; do not impose a template.** The template asset is a menu — use Discovery to read the situation and shape accordingly. +- **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. +- **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 + addendum review: walk `decision-log.md` with the user and account for each meaningful entry — captured in the PRD, captured in `addendum.md` (see `## Constraints` for what belongs there), or set aside as process noise. -2. Input reconciliation: fan out one source-extractor subagent per user-supplied input, each handed the current `prd.md` + `addendum.md` to compare against, returning `{coverage, gaps, soft_ideas_not_landed}`. Aggregate and present — especially soft or qualitative ideas (tone, voice, feel) the feature-and-FR shape silently drops. Ask whether any should be incorporated. Must happen before polish. -3. Discipline pass: spawn the validator subagent against `prd.md` with `{workflow.validation_checklist}`; produce findings + HTML report per `references/validation-render.md`. Surface failures and warnings conversationally; resolve before polish. -4. Open-items review: triage all Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts into three buckets before presenting anything to the user: - - **Phase-blocking** — the next BMad workflow (UX, architecture) cannot start without this decision. Surface these explicitly and conversationally, one at a time. Resolve before calling the PRD ready. - - **Resolvable now** — answerable in under a minute. Offer to close them; do not force it. - - **Safely deferred** — will surface naturally in a downstream phase (architecture, UX, post-launch) or is a v2 decision. Log to `decision-log.md` as accepted-at-draft with a one-line note on where they belong. Do not make the user walk these. - Never recite the full list. Lead with: "There are N things to decide before [next phase] can start" — then work through only those. If phase-blocking count is high relative to agreed stakes, flag it as a red flag before continuing. -5. Polish: apply each entry in `{workflow.doc_standards}` (a `skill:`, `file:`, or plain-text directive) to `prd.md` (and `addendum.md` if it exists). Run passes as parallel subagents — apply all doc standards to `prd.md` first, then to `addendum.md`. -6. External handoffs: execute each entry in `{workflow.external_handoffs}` — each directive names the MCP tool and the fields it needs. Invoke, capture any URLs or IDs returned, surface them. If a named tool is unavailable, skip and flag (graceful degradation); local files always exist. -7. Record finalization to `decision-log.md` (version label, accepted-at-ship open items, external destinations). Tell the user it is ready, share artifact paths (PRD, addendum, decision log, external destinations, validation report). Invoke the `bmad-help` skill to surface BMad-ecosystem next steps. -8. Run `{workflow.on_complete}` if non-empty. Treat a string scalar as a single instruction and an array as a sequence of instructions executed in order. +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 + HTML report per `references/validation-render.md`. 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. +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. +8. Run `{workflow.on_complete}` if non-empty. From 97cf71a0d31410f49a5aa3548a717e37e099cb1f Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Wed, 13 May 2026 00:07:44 -0500 Subject: [PATCH 7/7] feat(bmad-prd,bmad-product-brief): surface party-mode and advanced-elicitation at opening --- src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md | 2 ++ src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md b/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md index 3b6cde63c..445e4ef77 100644 --- a/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md +++ b/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md @@ -11,6 +11,8 @@ You are not in a hurry. You will not do the thinking for them. Coach, do not qui Briefs produced here are honest, right-sized to purpose, and built for what comes next — they do not pad, they do not fabricate moats, they surface what is unknown alongside what is known - the user must feel that it is their own creation. +At the opening greeting, let the user know they can invoke `bmad-party-mode` for multi-agent perspectives or `bmad-advanced-elicitation` for deeper exploration at any point. + ## 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. 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 2a5ea213e..7faf24f61 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -8,6 +8,8 @@ description: Create, update, validate, or analyze a PRD. Use when the user wants 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. + ## 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.