refactor(bmm): streamline bmad-product-brief into lean facilitator#2370
Merged
refactor(bmm): streamline bmad-product-brief into lean facilitator#2370
Conversation
Rewrites bmad-product-brief as an outcome-driven, intent-routed facilitator with a configurable reviewer panel. - Replace scripted prompt files with a concise SKILL.md - Add brief-shape detection and intent routing - Make the reviewer panel config-driven via customize.toml - Harden the required-reviewer gate - Add helper scripts and tests for panel resolution - Replace embedded resources with a single brief-template asset - Register skill metadata in module.yaml
📝 WalkthroughWalkthroughThe PR refactors ChangesProduct Brief Skill Refactor
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/bmm-skills/1-analysis/bmad-product-brief/customize.toml`:
- Around line 35-51: Add a docs page (or update the existing config docs)
describing the new brief customization knobs: brief_template, output_dir,
output_folder_name, and polish_skills; explain their purpose, defaults (e.g.,
brief_template = "assets/brief-template.md", output_dir =
"{planning_artifacts}/briefs", output_folder_name =
"brief-{project_name}-{date}"), how to override them in team/user TOML, and the
semantics/ordering of polish_skills (that skills run sequentially and can be
overridden). Reference the exact symbols brief_template, output_dir,
output_folder_name, and polish_skills and include examples of common overrides
and any caveats (parallel runs collide on inline edits) so users can apply the
new workflow knobs correctly.
In `@src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md`:
- Line 20: Update the skill doc to remove the contradiction between the
greeting/clarify step ("Greet `{user_name}` in `{communication_language}`.
Detect intent (create / update / validate); ask if unclear.") and the later
prohibition on asking in headless mode by specifying deterministic headless
fallback behavior: when running in headless mode, first attempt to infer intent
from available artifacts (e.g., product_brief, existing metadata,
previous_actions), if a single high-confidence intent is inferred proceed with
that intent, otherwise do not prompt the user and instead return/emit an
explicit failure status such as "INTENT_UNDETERMINED" or "NEED_USER_INPUT" (and
include reasons), and update references to "headless" and the intent-resolution
step in SKILL.md so the contract clearly states these fallback rules.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 7d366abd-23d6-45a3-9ffb-6e1380ecba66
📒 Files selected for processing (14)
src/bmm-skills/1-analysis/bmad-product-brief/SKILL.mdsrc/bmm-skills/1-analysis/bmad-product-brief/agents/artifact-analyzer.mdsrc/bmm-skills/1-analysis/bmad-product-brief/agents/opportunity-reviewer.mdsrc/bmm-skills/1-analysis/bmad-product-brief/agents/skeptic-reviewer.mdsrc/bmm-skills/1-analysis/bmad-product-brief/agents/web-researcher.mdsrc/bmm-skills/1-analysis/bmad-product-brief/assets/brief-template.mdsrc/bmm-skills/1-analysis/bmad-product-brief/bmad-manifest.jsonsrc/bmm-skills/1-analysis/bmad-product-brief/customize.tomlsrc/bmm-skills/1-analysis/bmad-product-brief/prompts/contextual-discovery.mdsrc/bmm-skills/1-analysis/bmad-product-brief/prompts/draft-and-review.mdsrc/bmm-skills/1-analysis/bmad-product-brief/prompts/finalize.mdsrc/bmm-skills/1-analysis/bmad-product-brief/prompts/guided-elicitation.mdsrc/bmm-skills/1-analysis/bmad-product-brief/resources/brief-template.mdsrc/bmm-skills/module.yaml
💤 Files with no reviewable changes (10)
- src/bmm-skills/1-analysis/bmad-product-brief/agents/opportunity-reviewer.md
- src/bmm-skills/1-analysis/bmad-product-brief/resources/brief-template.md
- src/bmm-skills/1-analysis/bmad-product-brief/agents/artifact-analyzer.md
- src/bmm-skills/1-analysis/bmad-product-brief/prompts/contextual-discovery.md
- src/bmm-skills/1-analysis/bmad-product-brief/bmad-manifest.json
- src/bmm-skills/1-analysis/bmad-product-brief/prompts/finalize.md
- src/bmm-skills/1-analysis/bmad-product-brief/agents/web-researcher.md
- src/bmm-skills/1-analysis/bmad-product-brief/agents/skeptic-reviewer.md
- src/bmm-skills/1-analysis/bmad-product-brief/prompts/draft-and-review.md
- src/bmm-skills/1-analysis/bmad-product-brief/prompts/guided-elicitation.md
🤖 Augment PR SummarySummary: Refactors Changes:
Notes: The new flow relies heavily on variable resolution and runtime conventions (config paths, run-folder naming), so validator compatibility and consistent config loading are important. 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
- Discovery now invites a brain dump and source material upfront, followed by "anything else?" before drilling - Create and Update modes explicitly invoke Discovery before drafting - Calibrate "make them sweat" to ease as the brief firms up - Update mode regenerates distillate.md when changes apply - Replace polish_skills with polish_passes: polymorphic entries (skill:/file:/plain-text), parallel subagents, applied automatically so the user sees a polished draft, not a polish review - Default persistent_facts to empty with opt-in examples instead of an unbounded project-context.md glob - Remove research-librarian, field-researcher, and skeptic agents no longer needed with this rework
…rief - Replace "Hold a working memory" with "Persistence is real-time": the workspace exists on disk and the user knows the path the moment Create intent is confirmed; decision-log.md is canonical memory so walk-away leaves nothing in the conversation - Add "Continuity across sessions": prior in-progress drafts for this project surface a resume offer
Adds an eval suite for bmad-product-brief following the Anthropic skill-creator schema, plus a new "Extract, don't ingest" constraint on the skill itself. Skill change: - New constraint: source artifacts (user-provided or run-discovered) enter the parent conversation as relevance-filtered extracts via subagents, not loaded wholesale. Keeps the parent context lean against transcripts, brainstorms, research reports, code, web results, and prior briefs. Evals (evals/bmm-skills/bmad-product-brief/): - evals.json: 8 artifact/behavioral evals covering Create one-shot, source-memo ingest, Update with contradiction surfacing, Validate inline, Headless mode, brainstorm filtering, research-report filtering, persona filtering. All scenarios use fictional entities (InsuLens, Branfield CC, Forkbird Kitchen, Mossridge Library, Sproutkeeper, Hatchet & Loop Studio, Brightway, Pantry Bridge). - triggers.json: 15 description-firing checks (7 should-fire, 8 should-not-fire) to catch under-triggering and adjacent-skill poaching. - files/: realistic fixtures including a brainstorm with the relevant idea buried at the end, a 3000-word market research report with the relevant section in the middle, and customer interviews with the target persona in position 3 of 4 — each shaped to test that filtering happens against the user's stated focus regardless of where the relevant material sits. Eval directory placement: top-level evals/ outside src/, matching the convention in anthropics/skills (zero of 17 production skills include an evals/ subdir; their skill-creator places dev workspaces as siblings to skill folders). Keeps evals out of any installer or marketplace.json distribution path.
- polish_passes -> doc_standards (TOML key + SKILL.md reference). Name
generalizes for every doc-producing skill: encodes standards applied at
finalize, not options.
- {run_folder} -> {doc_workspace}. Bound in Create to
{workflow.output_dir}/{workflow.output_folder_name}/; reused by Update,
Validate, Headless, and Finalize as the active brief's folder.
- On Activation Step 4 now resolves {date} explicitly (used by
output_folder_name default).
- Headless Mode: ambiguous-intent fallback is a `blocked` JSON status with
a `reason` field, no prompting. Resolves the activation/headless
contradiction flagged in review.
Refactor evals from 8 numbered single-shot tests into 16 typed evals: - Pattern A (A1-A8): artifact-correctness tests with headless prompts and precise, falsifiable expectations (no invented facts, right-sized output, file boundary enforcement) - Pattern B (B1-B8): process-discipline tests verifying decision-log fidelity, polish phase ordering, contradiction detection, and distillate generation - Pattern C (C1): config-compliance test for custom output paths and document_output_language Also tighten SKILL.md: add dependencies frontmatter, clarify headless override autonomy in Update (proceed when intent is clear; block when ambiguous), and make distillate skip explicit when bmad-distillator is not installed.
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrites
bmad-product-briefas an outcome-driven facilitator with three first-class intents: Create, Update, Validate. Replaces the scripted five-stage workflow and its subagent fan-outs with a single concise SKILL.md that trusts the model and names only the constraints, hooks, and contracts it cannot infer.Changes
SKILL.mdrewritten (117 → ~60 lines): role and honest-output paragraphs; standard six-step activation block; three intent paragraphs (Create / Update / Validate); short Headless, Discovery, Constraints, Finalize sections.assets/brief-template.mdadded — lean, adapt-aggressively guidance. Oldresources/brief-template.mdremoved (canonical folder name isassets/).customize.tomlupdated: keepsactivation_steps_prepend,activation_steps_append,persistent_facts,on_complete,brief_template; addsoutput_dir,output_folder_name, anddoc_standards(defaults, applied in order:bmad-editorial-review-structure,bmad-editorial-review-prose).agents/(artifact-analyzer, web-researcher, skeptic-reviewer, opportunity-reviewer) andprompts/(contextual-discovery, guided-elicitation, draft-and-review, finalize). Discovery, elicitation, and review now happen inline through the role and intent prompts rather than scripted handoffs.bmad-manifest.json— no longer load-bearing.Behavior
{doc_workspace}at{output_dir}/{output_folder_name}/:brief.md(frontmatter: title, status, created, updated),decision-log.mdworking-memory sidecar, optionaladdendum.md, optionaldistillate.md.blockedstatus when intent cannot be inferred.{workflow.doc_standards}→ optional distillate viabmad-distillator→ completion message andbmad-helpfor next steps →on_completeif set.Test plan
npm testpassesbmad-product-briefend-to-end on a sample idea, verify Create / Update / Validate intent routingcustomize.tomloverrides changeoutput_dir,doc_standards, andbrief_template