From c43964d7e657792cd0bfb025c6072a2cfd70f0db Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 28 Mar 2026 16:52:36 -0500 Subject: [PATCH] fix: harden bmad-prfaq for compaction resilience and context efficiency Add coaching persona re-anchors to all stage prompts so the behavioral directive survives context compaction. Add do-not-read guards at resume detection, headless mode, and input gathering to prevent parent agent context bloat. Add Stage 1 coaching notes capture. Adapt template and press release stage for non-commercial concept types. Cap subagent response token budgets. --- src/bmm-skills/1-analysis/bmad-prfaq/SKILL.md | 8 +++++--- .../bmad-prfaq/agents/artifact-analyzer.md | 2 +- .../bmad-prfaq/agents/web-researcher.md | 2 +- .../bmad-prfaq/assets/prfaq-template.md | 18 +++++++++--------- .../bmad-prfaq/references/customer-faq.md | 4 +++- .../bmad-prfaq/references/internal-faq.md | 2 ++ .../bmad-prfaq/references/press-release.md | 3 +++ .../bmad-prfaq/references/verdict.md | 1 + 8 files changed, 25 insertions(+), 15 deletions(-) diff --git a/src/bmm-skills/1-analysis/bmad-prfaq/SKILL.md b/src/bmm-skills/1-analysis/bmad-prfaq/SKILL.md index 446fa02e1..d9c865a78 100644 --- a/src/bmm-skills/1-analysis/bmad-prfaq/SKILL.md +++ b/src/bmm-skills/1-analysis/bmad-prfaq/SKILL.md @@ -25,10 +25,10 @@ Load available config from `{project-root}/_bmad/config.yaml` and `{project-root Resolve: `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`. -**Resume detection:** Check if `{planning_artifacts}/prfaq-{project_name}.md` already exists. If it does, read its frontmatter `stage` field and offer to resume from the next stage. If the user confirms, route directly to that stage's reference file. +**Resume detection:** Check if `{planning_artifacts}/prfaq-{project_name}.md` already exists. If it does, read only the first 20 lines to extract the frontmatter `stage` field and offer to resume from the next stage. Do not read the full document. If the user confirms, route directly to that stage's reference file. **Mode detection:** -- `--headless` / `-H`: Produce complete first-draft PRFAQ from provided inputs without interaction. Validate that inputs include at minimum: customer, problem, stakes, and solution concept. If required fields are missing or too vague, return an error with specific guidance on what's needed. Fan out artifact analyzer and web researcher subagents in parallel (see Contextual Gathering below), then create the output document at `{planning_artifacts}/prfaq-{project_name}.md` using `./assets/prfaq-template.md` and route to `./references/press-release.md`. +- `--headless` / `-H`: Produce complete first-draft PRFAQ from provided inputs without interaction. Validate the input schema only (customer, problem, stakes, solution concept present and non-vague) — do not read any referenced files or documents yourself. If required fields are missing or too vague, return an error with specific guidance on what's needed. Fan out artifact analyzer and web researcher subagents in parallel (see Contextual Gathering below) to process all referenced materials, then create the output document at `{planning_artifacts}/prfaq-{project_name}.md` using `./assets/prfaq-template.md` and route to `./references/press-release.md`. - Default: Full interactive coaching — the gauntlet. **Headless input schema:** @@ -69,7 +69,7 @@ When the user gets stuck, offer concrete suggestions based on what they've share **Contextual Gathering:** Once you understand the concept, gather external context before drafting begins. -1. **Ask about inputs:** "Do you have any existing documents, research, brainstorming, or materials I should review?" If the user provides paths or mentions prior artifacts, note them for subagent scanning. +1. **Ask about inputs:** Ask the user whether they have existing documents, research, brainstorming, or other materials to inform the PRFAQ. Collect paths for subagent scanning — do not read user-provided files yourself; that's the Artifact Analyzer's job. 2. **Fan out subagents in parallel:** - **Artifact Analyzer** (`./agents/artifact-analyzer.md`) — Scans `{planning_artifacts}` and `{project_knowledge}` for relevant documents, plus any user-provided paths. Receives the product intent summary so it knows what's relevant. - **Web Researcher** (`./agents/web-researcher.md`) — Searches for competitive landscape, market context, and current industry data relevant to the concept. Receives the product intent summary. @@ -78,6 +78,8 @@ When the user gets stuck, offer concrete suggestions based on what they've share **Create the output document** at `{planning_artifacts}/prfaq-{project_name}.md` using `./assets/prfaq-template.md`. Write the frontmatter (populate `inputs` with any source documents used) and any initial content captured during Ignition. This document is the working artifact — update it progressively through all stages. +**Coaching Notes Capture:** Before moving on, append a `` block to the output document: concept type and rationale, initial assumptions challenged, why this direction over alternatives discussed, key subagent findings that shaped the concept framing, and any user context captured that doesn't fit the PRFAQ itself. + **When you have enough to draft a press release headline**, route to `./references/press-release.md`. ## Stages diff --git a/src/bmm-skills/1-analysis/bmad-prfaq/agents/artifact-analyzer.md b/src/bmm-skills/1-analysis/bmad-prfaq/agents/artifact-analyzer.md index a97284615..69c7ff863 100644 --- a/src/bmm-skills/1-analysis/bmad-prfaq/agents/artifact-analyzer.md +++ b/src/bmm-skills/1-analysis/bmad-prfaq/agents/artifact-analyzer.md @@ -34,7 +34,7 @@ You will receive: ## Output -Return ONLY the following JSON object. No preamble, no commentary. Maximum 8 bullets per section. +Return ONLY the following JSON object. No preamble, no commentary. Keep total response under 1,500 tokens. Maximum 5 bullets per section — prioritize the most impactful findings. ```json { diff --git a/src/bmm-skills/1-analysis/bmad-prfaq/agents/web-researcher.md b/src/bmm-skills/1-analysis/bmad-prfaq/agents/web-researcher.md index 125412dc2..b09d738b3 100644 --- a/src/bmm-skills/1-analysis/bmad-prfaq/agents/web-researcher.md +++ b/src/bmm-skills/1-analysis/bmad-prfaq/agents/web-researcher.md @@ -26,7 +26,7 @@ You will receive: ## Output -Return ONLY the following JSON object. No preamble, no commentary. Maximum 5 bullets per section. +Return ONLY the following JSON object. No preamble, no commentary. Keep total response under 1,000 tokens. Maximum 5 bullets per section. ```json { diff --git a/src/bmm-skills/1-analysis/bmad-prfaq/assets/prfaq-template.md b/src/bmm-skills/1-analysis/bmad-prfaq/assets/prfaq-template.md index 6e17fa562..0d7f5f2f0 100644 --- a/src/bmm-skills/1-analysis/bmad-prfaq/assets/prfaq-template.md +++ b/src/bmm-skills/1-analysis/bmad-prfaq/assets/prfaq-template.md @@ -11,25 +11,25 @@ inputs: [] ## {Subheadline — one sentence: who benefits and what changes for them} -**{City, Date}** — {Opening paragraph: announce the product, state the customer problem, and the key benefit.} +**{City, Date}** — {Opening paragraph: announce the product/initiative, state the user's problem, and the key benefit.} -{Problem paragraph: the customer's pain today. Specific, concrete, felt. No mention of the solution yet.} +{Problem paragraph: the user's pain today. Specific, concrete, felt. No mention of the solution yet.} -{Solution paragraph: what changes for the customer. Benefits, not features. Outcomes, not implementation.} +{Solution paragraph: what changes for the user. Benefits, not features. Outcomes, not implementation.} -> "{Leader quote — the vision beyond the feature list.}" -> — {Name, Title} +> "{Leader/founder quote — the vision beyond the feature list.}" +> — {Name, Title/Role} ### How It Works -{The customer experience, step by step. Written from THEIR perspective. How they discover it, start using it, and get value from it.} +{The user experience, step by step. Written from THEIR perspective. How they discover it, start using it, and get value from it.} -> "{Customer quote — what a real person would say after using this. Must sound human, not like marketing copy.}" -> — {Customer Name, Role} +> "{User quote — what a real person would say after using this. Must sound human, not like marketing copy.}" +> — {Name, Role} ### Getting Started -{Clear, concrete path to first value. How to access, try, or buy.} +{Clear, concrete path to first value. How to access, try, adopt, or contribute.} --- diff --git a/src/bmm-skills/1-analysis/bmad-prfaq/references/customer-faq.md b/src/bmm-skills/1-analysis/bmad-prfaq/references/customer-faq.md index f8faa73ad..c677bb25d 100644 --- a/src/bmm-skills/1-analysis/bmad-prfaq/references/customer-faq.md +++ b/src/bmm-skills/1-analysis/bmad-prfaq/references/customer-faq.md @@ -1,10 +1,12 @@ **Language:** Use `{communication_language}` for all output. **Output Language:** Use `{document_output_language}` for documents. **Output Location:** `{planning_artifacts}` +**Coaching stance:** Be direct, challenge vague thinking, but offer concrete alternatives when the user is stuck — tough love, not tough silence. +**Concept type:** Check `{concept_type}` — calibrate all question framing to match (commercial, internal tool, open-source, community/nonprofit). # Stage 3: Customer FAQ -**Goal:** Validate the value proposition by asking the hardest questions a real customer would ask — and crafting answers that hold up under scrutiny. +**Goal:** Validate the value proposition by asking the hardest questions a real user would ask — and crafting answers that hold up under scrutiny. ## The Devil's Advocate diff --git a/src/bmm-skills/1-analysis/bmad-prfaq/references/internal-faq.md b/src/bmm-skills/1-analysis/bmad-prfaq/references/internal-faq.md index a57de57bc..42942826d 100644 --- a/src/bmm-skills/1-analysis/bmad-prfaq/references/internal-faq.md +++ b/src/bmm-skills/1-analysis/bmad-prfaq/references/internal-faq.md @@ -1,6 +1,8 @@ **Language:** Use `{communication_language}` for all output. **Output Language:** Use `{document_output_language}` for documents. **Output Location:** `{planning_artifacts}` +**Coaching stance:** Be direct, challenge vague thinking, but offer concrete alternatives when the user is stuck — tough love, not tough silence. +**Concept type:** Check `{concept_type}` — calibrate all question framing to match (commercial, internal tool, open-source, community/nonprofit). # Stage 4: Internal FAQ diff --git a/src/bmm-skills/1-analysis/bmad-prfaq/references/press-release.md b/src/bmm-skills/1-analysis/bmad-prfaq/references/press-release.md index cb343ee92..0bd21ff17 100644 --- a/src/bmm-skills/1-analysis/bmad-prfaq/references/press-release.md +++ b/src/bmm-skills/1-analysis/bmad-prfaq/references/press-release.md @@ -1,11 +1,14 @@ **Language:** Use `{communication_language}` for all output. **Output Language:** Use `{document_output_language}` for documents. **Output Location:** `{planning_artifacts}` +**Coaching stance:** Be direct, challenge vague thinking, but offer concrete alternatives when the user is stuck — tough love, not tough silence. # Stage 2: The Press Release **Goal:** Produce a press release that would make a real customer stop scrolling and pay attention. Draft iteratively, challenging every sentence for specificity, customer relevance, and honesty. +**Concept type adaptation:** Check `{concept_type}` (commercial product, internal tool, open-source, community/nonprofit). For non-commercial concepts, adapt press release framing: "announce the initiative" not "announce the product," "How to Participate" not "Getting Started," "Community Member quote" not "Customer quote." The structure stays — the language shifts to match the audience. + ## The Forge The press release is the heart of Working Backwards. It has a specific structure, and each part earns its place by forcing a different type of clarity: diff --git a/src/bmm-skills/1-analysis/bmad-prfaq/references/verdict.md b/src/bmm-skills/1-analysis/bmad-prfaq/references/verdict.md index c5f1b2180..f77a95020 100644 --- a/src/bmm-skills/1-analysis/bmad-prfaq/references/verdict.md +++ b/src/bmm-skills/1-analysis/bmad-prfaq/references/verdict.md @@ -1,6 +1,7 @@ **Language:** Use `{communication_language}` for all output. **Output Language:** Use `{document_output_language}` for documents. **Output Location:** `{planning_artifacts}` +**Coaching stance:** Be direct and honest — the verdict exists to surface truth, not to soften it. But frame every finding constructively. # Stage 5: The Verdict