fix(prd): require user confirmation before de-scoping requirements or inventing phases#1927
fix(prd): require user confirmation before de-scoping requirements or inventing phases#1927sunilp wants to merge 2 commits intobmad-code-org:mainfrom
Conversation
|
good suggested change here, it you can resolve the merge conflicts I will get this in @sunilp |
|
@bmadcode merge conflicts resolved — rebased against latest main. All original changes intact and verified. |
📝 WalkthroughWalkthroughUpdates the PRD creation workflow's scoping step to require explicit user confirmation before making consequential scoping decisions, including deferrals, de-scoping, or phasing. Introduces conditional handling for phased versus single-release delivery modes and restructures the content generation accordingly. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
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 Tip You can customize the high-level summary generated by CodeRabbit.Configure the |
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (6)
src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.md (6)
1-1:⚠️ Potential issue | 🟠 MajorTitle still hard-codes phased framing and conflicts with single-release mode.
Line 1 (“MVP & Future Features”) implies phased delivery by default, which contradicts the new consent model. Use a neutral title that covers both modes.
Suggested fix
-# Step 8: Scoping Exercise - MVP & Future Features +# Step 8: Scoping Exercise - Scope Definition (Phased or Single-Release)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.md` at line 1, The header in step-08-scoping.md currently hard-codes a phased delivery framing ("MVP & Future Features") which conflicts with single-release mode; change the title line to a neutral scoping header that works for both modes—for example "Scope: Core and Optional Features" or "Scoping: Core and Optional Features"—and update any adjacent introductory sentence that repeats the phased wording to use neutral terms like "core" and "optional/future" so the document does not assume phased releases.
227-227:⚠️ Potential issue | 🟠 MajorDownstream step compatibility is not guarded for single-release mode.
Line 227 always transitions to step-09, but step-09’s completeness check explicitly asks about “MVP scope section.” Single-release output may not have that section, so this needs a handoff note or step-09 compatibility update.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.md` at line 227, The transition in step-08-scoping.md unconditionally advances to step-09-functional.md and appends this step name to stepsCompleted, but step-09 expects an “MVP scope section” which may be absent in single-release mode; update the handoff to guard compatibility by adding a conditional or note: when running in single-release mode (or when the output lacks the MVP scope section) do not jump straight to step-09 or instead append a compatibility flag to the frontmatter (e.g., add a releaseMode or skipMVP boolean alongside stepsCompleted) and modify the handoff text in step-08-scoping.md to either point to an alternative next step or include instructions for creating a minimal MVP scope before invoking step-09-functional.md so step-09’s completeness check will succeed.
39-39:⚠️ Potential issue | 🟠 MajorTask statement still mandates phase-based prioritization.
Line 39 says “prioritize features across development phases,” which reintroduces automatic phasing. This should be conditional on explicit user choice.
Suggested fix
-Conduct comprehensive scoping exercise to define MVP boundaries and prioritize features across development phases. +Conduct comprehensive scoping exercise to define release boundaries and prioritize features based on the user's chosen delivery mode (phased or single-release).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.md` at line 39, The sentence "prioritize features across development phases" in step-08-scoping.md mandates phase-based prioritization; change it to make phase-based prioritization conditional on user choice by rephrasing to something like "optionally prioritize features across development phases if the stakeholder opts for a phased approach" or add a preceding conditional clause; update the line containing "prioritize features across development phases" so it only recommends phasing when the user explicitly selects a phased delivery strategy and mention the user choice/option in the same sentence to ensure the scoping task is not prescriptive.
153-212: 🛠️ Refactor suggestion | 🟠 MajorNo explicit traceability artifact despite “all requirements accounted for” guarantee.
Lines 243–246 require full accountability, but the content templates in Lines 153–212 lack a required “requirement mapping / disposition” section. Without a mandatory mapping, the guarantee is unverifiable.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.md` around lines 153 - 212, Add a mandatory "Requirement Mapping / Disposition" section to both the phased template under "## Project Scoping & Phased Development" and the single-release template under "## Project Scoping" that ties each listed feature/journey to a verifiable disposition (e.g., mapped requirement ID, phase, status, and acceptance criteria); update the placeholders (e.g., {{essential_journeys_for_mvp}}, {{list_of_must_have_features}}, {{all_journeys}}) to reference the new mapping (for example {{requirement_mapping}}) and ensure the section requires entries for Requirement ID, Description, Assigned Phase, Priority, and Acceptance Criteria so the "all requirements accounted for" guarantee is auditable.
100-114:⚠️ Potential issue | 🟡 MinorPhase taxonomy drifts (“Vision” vs “Expansion”), weakening consistency.
Lines 97 and 259 reference “Vision,” but Line 110 labels Phase 3 as “Expansion.” This creates ambiguous downstream references and traceability breakage.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.md` around lines 100 - 114, The document uses two different labels for the final phase ("Vision" appears elsewhere while the header reads "Phase 3: Expansion"), causing inconsistent references; pick a single canonical term and make it consistent across the file by renaming the header "Phase 3: Expansion" to "Phase 3: Vision" (or alternatively replace all "Vision" references with "Expansion") and update any subsequent mentions or cross-references so every reference (e.g., the "Phase 3" header and the occurrences currently labeled "Vision") use the same term for traceability.
217-219:⚠️ Potential issue | 🟠 MajorMenu presentation still assumes a phased roadmap exists.
Line 218 always says “phased roadmap,” even when single-release is selected. This can force the model to fabricate phase artifacts right before save.
Suggested fix
-- Highlight MVP boundaries and phased roadmap +- Highlight release boundaries and prioritization (phased roadmap only if phased delivery was selected)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.md` around lines 217 - 219, The menu text "phased roadmap" should be rendered conditionally so it doesn't appear when a single-release option is chosen; update the copy generation in step-08-scoping.md so the line that currently reads "phased roadmap" (and the menu bullets: "Show strategic scoping plan (using structure from step 6)" / "Highlight MVP boundaries and phased roadmap" / "Ask if they'd like to refine further, get other perspectives, or proceed") uses the selected release mode variable (e.g., roadmapType or releaseMode) to choose wording—use "phased roadmap" only when roadmapType == "phased", otherwise use "release plan" or "single-release plan" and remove any phrasing that prompts generation of phase artifacts for single-release flows to avoid fabricating phases.
🧹 Nitpick comments (1)
src/core/tasks/bmad-create-prd/steps-c/step-11-polish.md (1)
141-141: “Scope decisions” should explicitly include requirement disposition traceability.Given the new scoping guarantees, this line should preserve not just outcomes, but requirement-level disposition (in-scope/deferred) and user approval state. Otherwise, polish can silently break auditability.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/tasks/bmad-create-prd/steps-c/step-11-polish.md` at line 141, Update the polish wording that currently reads "All scope decisions (whether phased or single-release)" to explicitly require preservation of requirement-level disposition and user approval state: change the line in step-11-polish.md to mention "All scope decisions (whether phased or single-release), including requirement-level disposition (in-scope/deferred) and associated user approval state and traceability (requirement IDs and approval records)". Ensure the phrasing enforces auditability and trace links so downstream polishing cannot drop disposition or approval metadata.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.md`:
- Around line 80-83: Update the "⚠️ SCOPE CHANGE CONFIRMATION GATE" section to
also require explicit user confirmation before creating any consequential
phase-based artifacts (e.g., phase tags, labels, or follow-on prompts) that
would be introduced as a result of scope changes; modify the paragraph under
that header to add a bullet that instructs the agent to present any proposed
artifact creation as a recommendation ("I'd recommend creating X because
[reason]. Do you agree?") and to proceed only after explicit user approval;
apply the same addition to the duplicate guidance referenced at lines 258-260 so
both places enforce the artifact-creation confirmation gate.
- Line 122: The scoping prompt in step-08-scoping.md still asks “**Where does
your current vision fit in this development sequence?**” even for single-release
mode; update the content to branch by release mode: if the selected mode equals
"single-release" (or the internal variable controlling mode, e.g.,
releaseMode/surveyMode), replace that question with a single-release appropriate
prompt such as “How does your current vision map to this single upcoming
release?”; otherwise keep the existing phased-sequence wording. Locate the
prompt string in step-08-scoping.md and implement the conditional selection so
the correct question is shown based on the release-mode flag.
- Line 95: Replace the nonstandard modal phrasing "wants phased delivery" in
step-08-scoping.md with a clearer, more direct formulation such as "requests
phased delivery" or "chooses phased delivery"; locate the phrase "wants phased
delivery" (the heading/line shown in the diff) and update it so the instruction
reads e.g., "When the user requests phased delivery, guide mapping of features
across development phases" to improve clarity and pass static analysis.
- Around line 95-99: The current guidance hard-codes exactly three phases
("Phase 1 (MVP), Phase 2 (Growth), Phase 3 (Vision)") which conflicts with
"phases the user defined"; update the wording under "When the user wants phased
delivery" to instruct mapping features across the user-defined number and labels
of phases (e.g., "Phase A, Phase B, ..." or "Alpha/Beta/GA" as examples), remove
the fixed Phase 1/2/3 list, and add a short note to ensure clear progression and
explicit dependencies between whatever phases the user defines so the content
respects arbitrary phase counts and custom labels.
In `@src/core/tasks/bmad-create-prd/steps-c/step-11-polish.md`:
- Around line 141-142: The preservation rule in the polish step currently only
lists “All scope decisions (whether phased or single-release)” but omits the
consent-critical evidence required by step-08; update the bullet to explicitly
preserve “consent-critical evidence (explicit confirmations and rationales for
scope changes required by step-08)” and add a note that deduplication must not
remove these evidence items—ensure the polish step’s preservation list (the “All
scope decisions…” bullet in step-11-polish.md) includes that explicit language
so deduplication logic retains confirmations/rationales referenced by step-08.
---
Outside diff comments:
In `@src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.md`:
- Line 1: The header in step-08-scoping.md currently hard-codes a phased
delivery framing ("MVP & Future Features") which conflicts with single-release
mode; change the title line to a neutral scoping header that works for both
modes—for example "Scope: Core and Optional Features" or "Scoping: Core and
Optional Features"—and update any adjacent introductory sentence that repeats
the phased wording to use neutral terms like "core" and "optional/future" so the
document does not assume phased releases.
- Line 227: The transition in step-08-scoping.md unconditionally advances to
step-09-functional.md and appends this step name to stepsCompleted, but step-09
expects an “MVP scope section” which may be absent in single-release mode;
update the handoff to guard compatibility by adding a conditional or note: when
running in single-release mode (or when the output lacks the MVP scope section)
do not jump straight to step-09 or instead append a compatibility flag to the
frontmatter (e.g., add a releaseMode or skipMVP boolean alongside
stepsCompleted) and modify the handoff text in step-08-scoping.md to either
point to an alternative next step or include instructions for creating a minimal
MVP scope before invoking step-09-functional.md so step-09’s completeness check
will succeed.
- Line 39: The sentence "prioritize features across development phases" in
step-08-scoping.md mandates phase-based prioritization; change it to make
phase-based prioritization conditional on user choice by rephrasing to something
like "optionally prioritize features across development phases if the
stakeholder opts for a phased approach" or add a preceding conditional clause;
update the line containing "prioritize features across development phases" so it
only recommends phasing when the user explicitly selects a phased delivery
strategy and mention the user choice/option in the same sentence to ensure the
scoping task is not prescriptive.
- Around line 153-212: Add a mandatory "Requirement Mapping / Disposition"
section to both the phased template under "## Project Scoping & Phased
Development" and the single-release template under "## Project Scoping" that
ties each listed feature/journey to a verifiable disposition (e.g., mapped
requirement ID, phase, status, and acceptance criteria); update the placeholders
(e.g., {{essential_journeys_for_mvp}}, {{list_of_must_have_features}},
{{all_journeys}}) to reference the new mapping (for example
{{requirement_mapping}}) and ensure the section requires entries for Requirement
ID, Description, Assigned Phase, Priority, and Acceptance Criteria so the "all
requirements accounted for" guarantee is auditable.
- Around line 100-114: The document uses two different labels for the final
phase ("Vision" appears elsewhere while the header reads "Phase 3: Expansion"),
causing inconsistent references; pick a single canonical term and make it
consistent across the file by renaming the header "Phase 3: Expansion" to "Phase
3: Vision" (or alternatively replace all "Vision" references with "Expansion")
and update any subsequent mentions or cross-references so every reference (e.g.,
the "Phase 3" header and the occurrences currently labeled "Vision") use the
same term for traceability.
- Around line 217-219: The menu text "phased roadmap" should be rendered
conditionally so it doesn't appear when a single-release option is chosen;
update the copy generation in step-08-scoping.md so the line that currently
reads "phased roadmap" (and the menu bullets: "Show strategic scoping plan
(using structure from step 6)" / "Highlight MVP boundaries and phased roadmap" /
"Ask if they'd like to refine further, get other perspectives, or proceed") uses
the selected release mode variable (e.g., roadmapType or releaseMode) to choose
wording—use "phased roadmap" only when roadmapType == "phased", otherwise use
"release plan" or "single-release plan" and remove any phrasing that prompts
generation of phase artifacts for single-release flows to avoid fabricating
phases.
---
Nitpick comments:
In `@src/core/tasks/bmad-create-prd/steps-c/step-11-polish.md`:
- Line 141: Update the polish wording that currently reads "All scope decisions
(whether phased or single-release)" to explicitly require preservation of
requirement-level disposition and user approval state: change the line in
step-11-polish.md to mention "All scope decisions (whether phased or
single-release), including requirement-level disposition (in-scope/deferred) and
associated user approval state and traceability (requirement IDs and approval
records)". Ensure the phrasing enforces auditability and trace links so
downstream polishing cannot drop disposition or approval metadata.
🪄 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: c062a22d-deba-4a9b-83b3-0a93f3d4f01c
📒 Files selected for processing (2)
src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.mdsrc/core/tasks/bmad-create-prd/steps-c/step-11-polish.md
| **⚠️ SCOPE CHANGE CONFIRMATION GATE:** | ||
| - If you believe any user-specified requirement should be deferred or de-scoped, you MUST present this to the user and get explicit confirmation BEFORE removing it from scope | ||
| - Frame it as a recommendation, not a decision: "I'd recommend deferring X because [reason]. Do you agree, or should it stay in scope?" | ||
| - NEVER silently move user requirements to a later phase or exclude them from MVP |
There was a problem hiding this comment.
Confirmation gate covers scope removal but not consequential artifact creation.
The issue objective includes avoiding unapproved follow-on artifacts (phase tags/labels/prompts). Current rules focus on de-scoping confirmation only. Add an explicit gate for creating phase-based artifacts when not user-approved.
Also applies to: 258-260
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.md` around lines 80 -
83, Update the "⚠️ SCOPE CHANGE CONFIRMATION GATE" section to also require
explicit user confirmation before creating any consequential phase-based
artifacts (e.g., phase tags, labels, or follow-on prompts) that would be
introduced as a result of scope changes; modify the paragraph under that header
to add a bullet that instructs the agent to present any proposed artifact
creation as a recommendation ("I'd recommend creating X because [reason]. Do you
agree?") and to proceed only after explicit user approval; apply the same
addition to the duplicate guidance referenced at lines 258-260 so both places
enforce the artifact-creation confirmation gate.
| - **If the input documents explicitly request phased delivery:** Guide mapping of features across the phases the user defined. | ||
| - **If scope is unclear:** ASK the user whether they want phased delivery or a single release before proceeding. | ||
|
|
||
| **When the user wants phased delivery**, guide mapping of features across development phases: |
There was a problem hiding this comment.
Wording issue at Line 95 reduces instruction clarity.
Line 95 (“wants phased delivery”) is flagged by static analysis as nonstandard modal phrasing. Use a clearer form to reduce interpretation drift.
Suggested fix
-**When the user wants phased delivery**, guide mapping of features across development phases:
+**When the user wants delivery to be phased**, guide mapping of features across development phases:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| **When the user wants phased delivery**, guide mapping of features across development phases: | |
| **When the user wants delivery to be phased**, guide mapping of features across development phases: |
🧰 Tools
🪛 LanguageTool
[style] ~95-~95: The double modal “wants phased” is nonstandard (only accepted in certain dialects). Consider “to be phased”.
Context: ...fore proceeding. When the user wants phased delivery, guide mapping of features a...
(NEEDS_FIXED)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.md` at line 95,
Replace the nonstandard modal phrasing "wants phased delivery" in
step-08-scoping.md with a clearer, more direct formulation such as "requests
phased delivery" or "chooses phased delivery"; locate the phrase "wants phased
delivery" (the heading/line shown in the diff) and update it so the instruction
reads e.g., "When the user requests phased delivery, guide mapping of features
across development phases" to improve clarity and pass static analysis.
| **When the user wants phased delivery**, guide mapping of features across development phases: | ||
|
|
||
| - Structure as Phase 1 (MVP), Phase 2 (Growth), Phase 3 (Vision) | ||
| - Ensure clear progression and dependencies | ||
|
|
There was a problem hiding this comment.
Phased path is over-constrained to exactly 3 phases.
Line 95 says “across development phases,” but Lines 97–99 force Phase 1/2/3. That conflicts with “phases the user defined” (Line 92). Respect user-defined phase count/labels.
Suggested fix
-**When the user wants phased delivery**, guide mapping of features across development phases:
-
-- Structure as Phase 1 (MVP), Phase 2 (Growth), Phase 3 (Vision)
-- Ensure clear progression and dependencies
+**When the user wants phased delivery**, guide mapping of features across the phases the user requests/approves:
+
+- Use user-provided phase labels and count; if none are provided, propose a default and ask for confirmation
+- Ensure clear progression and dependencies🧰 Tools
🪛 LanguageTool
[style] ~95-~95: The double modal “wants phased” is nonstandard (only accepted in certain dialects). Consider “to be phased”.
Context: ...fore proceeding. When the user wants phased delivery, guide mapping of features a...
(NEEDS_FIXED)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.md` around lines 95 -
99, The current guidance hard-codes exactly three phases ("Phase 1 (MVP), Phase
2 (Growth), Phase 3 (Vision)") which conflicts with "phases the user defined";
update the wording under "When the user wants phased delivery" to instruct
mapping features across the user-defined number and labels of phases (e.g.,
"Phase A, Phase B, ..." or "Alpha/Beta/GA" as examples), remove the fixed Phase
1/2/3 list, and add a short note to ensure clear progression and explicit
dependencies between whatever phases the user defines so the content respects
arbitrary phase counts and custom labels.
| - Focus must-have vs nice-to-have analysis on what ships in this release | ||
| - Do NOT create phases — use must-have/nice-to-have priority within the single release | ||
|
|
||
| **Where does your current vision fit in this development sequence?**" |
There was a problem hiding this comment.
Single-release flow still asks a phase-sequence question.
Line 122 (“development sequence”) is invalid when user selected single release. Branch this prompt by mode.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/core/tasks/bmad-create-prd/steps-c/step-08-scoping.md` at line 122, The
scoping prompt in step-08-scoping.md still asks “**Where does your current
vision fit in this development sequence?**” even for single-release mode; update
the content to branch by release mode: if the selected mode equals
"single-release" (or the internal variable controlling mode, e.g.,
releaseMode/surveyMode), replace that question with a single-release appropriate
prompt such as “How does your current vision map to this single upcoming
release?”; otherwise keep the existing phased-sequence wording. Locate the
prompt string in step-08-scoping.md and implement the conditional selection so
the correct question is shown based on the release-mode flag.
| - All scope decisions (whether phased or single-release) | ||
| - All non-functional requirements |
There was a problem hiding this comment.
Preservation rule is incomplete for consent-critical evidence.
Line 141 preserves “scope decisions,” but not the evidence required by step-08 (explicit confirmations/rationale for scope changes). In this polish step, deduplication can strip that evidence while still keeping a high-level decision summary.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/core/tasks/bmad-create-prd/steps-c/step-11-polish.md` around lines 141 -
142, The preservation rule in the polish step currently only lists “All scope
decisions (whether phased or single-release)” but omits the consent-critical
evidence required by step-08; update the bullet to explicitly preserve
“consent-critical evidence (explicit confirmations and rationales for scope
changes required by step-08)” and add a note that deduplication must not remove
these evidence items—ensure the polish step’s preservation list (the “All scope
decisions…” bullet in step-11-polish.md) includes that explicit language so
deduplication logic retains confirmations/rationales referenced by step-08.
…ements or inventing phases
step-08-scoping.md: - Neutral title replacing hard-coded "MVP & Future Features" - Task statement no longer mandates phase-based prioritization - Confirmation gate now covers artifact creation, not just de-scoping - Phased delivery uses user-defined phase labels/count instead of fixed 3 - "wants phased" phrasing replaced with "requests/chooses" - Development sequence question branches by release mode - Menu text conditional on delivery mode (no "phased roadmap" for single-release) - Handoff to step-09 now persists releaseMode in frontmatter - New failure mode for unapproved phase artifact creation step-11-polish.md: - Preservation rule now includes consent-critical evidence from step 8
de1b441 to
36f9df6
Compare
What
Fixes the inverted permission model in the PRD scoping workflow where the agent silently makes consequential scoping decisions while prompting for trivial confirmations.
Why
The PRD workflow autonomously de-scopes user-specified requirements into fabricated phases (MVP/Growth/Vision) without asking, even when the user input explicitly lists all components as core requirements. Meanwhile, trivial workflow transitions require constant user confirmation. This leads to incorrect PRDs that contradict their own input documents.
Fixes #1693
How
Changes to step-08-scoping.md:
Changes to step-11-polish.md:
Testing