From 4baca1880eec1f598c5e2ebb9f3e88e32433399c Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Tue, 12 May 2026 23:21:40 -0500 Subject: [PATCH] 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.