feat(workflows): add brownfield epic scoping to detect file churn (#1823)#1826
Open
anderewrey wants to merge 1 commit intobmad-code-org:mainfrom
Open
Conversation
…ad-code-org#1823) Add design completeness gate, file overlap check, and validation to prevent unnecessary file churn when epics target the same component.
Author
|
When asked for reasoning on the epic partioning, here's its reply: With the original workflow, here's the reasoning: |
📝 WalkthroughWalkthroughThe changes extend the Create Epics and Stories workflow with new file overlap detection and consolidation guidance, addressing brownfield feature scoping. Step 02 introduces file churn prevention principles and multi-step review processes, while Step 04 adds explicit file churn validation checks to the epic structure review. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 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)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). 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: 10
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md (2)
152-166:⚠️ Potential issue | 🟠 MajorTemplate format missing overlap annotation field.
Step B (line 139) directs agents to "annotate with considerations about overlap" and Step C reviews file overlap for consolidation decisions, but the epics_list template (lines 152-166) provides no field to record:
- File overlap percentage or list
- Consolidation decision rationale
- Whether overlap was reviewed and deemed acceptable
Without a designated place to document these decisions, the validation step (Step 4 in step-04-final-validation.md, line 118) asks for "consolidation was explicitly considered and rejected with rationale"—but where is that rationale recorded?
Suggested template extension
### Epic 1: [Epic Title] [Epic goal statement - what users can accomplish] **FRs covered:** FR1, FR2, FR3, etc. +**File Overlap Notes:** [None | Shares X files with Epic Y - justified by: risk boundary/feedback loop/context limit]🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md` around lines 152 - 166, The epics_list template lacks a place to record overlap analysis required by Step B/C and by final validation; update the epics_list template to include explicit overlap annotation fields for each epic such as "Overlap (files/percentage):", "Overlap reviewed: (yes/no)", and "Consolidation decision & rationale:" so agents can record which files overlap, the measured overlap percentage or list, whether the overlap was reviewed, and why consolidation was accepted or rejected (this ties into Step B's "annotate with considerations about overlap", Step C file-overlap review, and Step 4 in step-04-final-validation.md).
119-211:⚠️ Potential issue | 🟡 MinorInconsistent step naming convention within Section 3.
Section 3 ("Design Epic Structure Collaboratively") uses letter-based sub-steps (Step A, B, C, D at lines 119-150) then switches to number-based sub-steps (4, 5, 6, 7 at lines 168-211) without explanation or hierarchy change.
This inconsistency makes it unclear whether:
- Steps 4-7 are siblings of Steps A-D (implying A-D should be 0-3)?
- Steps 4-7 are at the same level as Section 3 (in which case they should be "### 4" not under Section 3)?
- This is intentional sub-sub-section numbering (then "Step" prefix should distinguish levels)?
Consistent hierarchy labeling is essential for workflow navigation, especially when agents are instructed to "read fully and follow" specific steps.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md` around lines 119 - 211, In Section 3 ("Design Epic Structure Collaboratively") the sub-step labels are inconsistent: the document uses "Step A/B/C/D" for the initial sub-steps (Step A: Assess Context..., Step B: Propose Epic Structure, Step C: Review for File Overlap, Step D: Create the epics_list) but then switches to numeric "4. Present Epic List for Review", "5. Create Requirements Coverage Map", "6. Collaborative Refinement", "7. Get Final Approval"; unify the hierarchy by choosing one convention and applying it consistently—either rename Steps A-D to "Step 1/2/3/4" (or "4.1/4.2..." if 4–7 are siblings) or rename numeric 4–7 to "Step E/F/G/H" (or "Step 3.E..." to indicate nesting), and ensure headings show correct nesting (e.g., "###" level matches) so that references like "Step A", "Step D: Create the epics_list", and "4. Present Epic List for Review" consistently reflect their intended sibling/child relationship throughout the section.
🧹 Nitpick comments (2)
src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md (1)
226-238: Menu handling lacks error boundaries for invalid input.Line 230 handles invalid input with "help user respond then [Redisplay Menu Options]" but provides no safeguard against:
- Repeated invalid input (user types gibberish 10 times)
- Infinite loops (agent and user both confused)
- Stuck state (menu re-displays indefinitely)
While this may be acceptable UX for human-in-the-loop workflows, the lack of error boundaries means there's no escape hatch or escalation path when the interaction breaks down.
Potential guard rails
Add a note after line 230:
- After 3 consecutive unrecognized inputs, offer: "Would you like to [C]ontinue with current epics, [R]evise epic structure, or [H]elp with menu options?"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md` around lines 226 - 238, The menu handling branch "IF Any other comments or queries: help user respond then [Redisplay Menu Options]" lacks error boundaries; add a guard that tracks consecutive unrecognized inputs for the menu handler (the "IF Any other comments or queries" flow) and after 3 consecutive invalid responses present an escape prompt offering "[C]ontinue with current epics, [R]evise epic structure, or [H]elp with menu options" (and an option to escalate/exit), reset the invalid-input counter after a valid selection or escalation, and ensure the execution rules (ALWAYS halt and wait; ONLY proceed on 'C') still apply while preventing infinite redisplay loops by treating the escape choices as explicit next actions.src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md (1)
113-118: File Churn Check isolated from Dependency Validation.The File Churn Check (Section 4, lines 113-118) validates whether epics share files, while Dependency Validation (Section 5, lines 120-138) validates epic independence. These are related concerns:
- If multiple epics are consolidated due to file churn (Step 2, Step C), the dependency chain changes—Epic 2 and Epic 3 no longer exist as separate entities.
- Dependency Validation should verify that consolidation didn't introduce forward dependencies within the merged epic's stories.
- Currently, these validations run independently without cross-referencing each other's outcomes.
Consider adding a cross-check: "If File Churn Check resulted in consolidation, verify that the consolidated epic's story dependencies remain backward-only (Section 5)."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md` around lines 113 - 118, Add a cross-check between "File Churn Check" and "Dependency Validation": when "File Churn Check" triggers consolidation (Step 2, Step C), run an additional verification in the "Dependency Validation" step to ensure the consolidated epic's story dependencies remain backward-only (no forward dependencies introduced by merging Epic 2/Epic 3). Update the logic around the File Churn Check outcome to pass a "consolidated" flag or list of merged epics into Dependency Validation and, inside the Dependency Validation flow, re-evaluate story dependency direction for any consolidated epic and surface failures if forward dependencies exist.
🤖 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/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md`:
- Line 134: Define the term "core files" once at the principles/definitions
section (where the principal term is introduced around line 80)—explicitly state
what it includes (e.g., files under src/core/, shared domain models,
controllers, or any files modified by multiple epics) and any quantitative
criteria (lines/deps) if applicable—then update Step B (the line containing
"whether epics share the same core files") to reference that single definition
(e.g., "see 'core files' definition in Principles") instead of reintroducing the
phrase, ensuring consistent terminology across the document.
- Around line 147-148: Summary: The guidance to "merge the epic FRs into a
single epic" (line 147) conflicts with the "Each epic must be standalone" rule
(line 52) and principle `#3` (line 77); add explicit reconciliation steps. Update
the step to require that when consolidating epics (the "merge the epic FRs into
a single epic" action) you must (1) re-evaluate and document the merged epic's
public interfaces and acceptance criteria so it remains independently
releasable, (2) update the dependency graph and reassign original epic IDs as
sub-features or milestones so subsequent epics (original Epic 4+) reference the
merged epic’s new interface rather than internal functionality, (3) split the
merged epic into incremental delivery milestones (preserving "each story must
still fit within a single dev agent's context" from the same step) and ensure
each milestone is independently testable, and (4) add a validation gate to the
workflow to re-run the "Each epic must be standalone" check after consolidation
so consolidation cannot violate principle `#3`.
- Line 80: Principle `#6` ("Implementation Efficiency") is vague because "core
files" and "consider consolidating epics" lack operational definition; update
the bullet to define "core files" (e.g., modules or files touched by >N
features, shared libraries, public APIs, or files with high change frequency)
and add concrete consolidation thresholds (e.g., consolidate epics when they
each touch the same file and overlap ≥50% of modified files or when ≥2 epics
modify the same critical/shared module); reference the existing phrase
"Implementation Efficiency" and the "consider consolidating epics that all
modify the same core files" line when making the change so readers can find and
replace that sentence with the clarified definition and thresholds.
- Around line 119-150: The new Step C (Review for File Overlap) was added and
Steps were renumbered (Step B → Step D) but you didn't provide migration
guidance for users with in-progress workflows; add a concise "Note for
in-progress workflows" before the Section 3 / "Step C" heading that instructs
users who completed epic design under the previous workflow to re-run the File
Overlap Review (Step C) to validate file churn patterns before story creation,
state whether previously approved epics must be re-validated or can be exempted
(choose and document the policy), and mention impact on epics_list generation so
readers know if they must update existing epics.md files or can proceed without
changes.
- Around line 99-110: Update the WRONG/CORRECT examples in
step-02-design-epics.md to be conditional and to operationalize "design
completeness": change the unconditional label to "If design is fully
pre-designed (see checklist) then this is WRONG; otherwise splitting may be
justified." Add a short checklist or criteria under the existing "Step A /
design completeness" reference that defines "complete" (e.g., UX wireframes, API
contracts, acceptance criteria, integration points) and a one-line explicit
harms list (merge conflicts, increased cognitive load, deployment risk, testing
overhead) so readers can weigh trade-offs and follow the right branch in the
examples.
- Around line 121-124: The guidance using terms like "outcome is certain",
"validated design", and "direction changes between epics are unlikely" is
subjective; replace these with an explicit decision rubric: define "outcome is
certain" as completion of Architecture doc + UX mockups + Test Design checklist
plus stakeholder sign-off (or specify required artifacts), define "validated
design" by per-artifact acceptance criteria (e.g., Architecture: component
diagram, interfaces, performance constraints; UX: user flows, usability review
notes; Test Design: E2E scenarios and test cases), and quantify "direction
changes...unlikely" with a risk threshold (e.g., <20% change probability) and
concrete signals that increase risk (open technical unknowns, unresolved
stakeholder feedback, compliance/regulatory review pending); then add a short
decision checklist under the "Split into multiple epics" paragraph that
references these criteria so agents can reproducibly choose consolidation vs
splitting.
- Around line 141-149: Step C currently asks reviewers to detect "meaningful
overlap" and ensure epics fit a "single dev agent's context" but omits
measurable criteria and a file-enumeration process; update the document to (1)
move the explicit example ("same component end-to-end" with model/controller/web
form/web API) from the example into the principle so "meaningful overlap" is
defined up front, (2) define "single dev agent's context" with concrete sizing
guidance (e.g., token limits or max file count referencing the existing
"quick-dev-new-preview" story SPECS range of 900–1600 tokens or an agreed
file/complexity cap) under the Step C heading, and (3) add a clear procedure for
enumerating candidate files (e.g., extract file lists from FR descriptions or
defer to Step 3 and validate in Step 4) so reviewers know where to source file
modification lists and when to perform the overlap check; update references to
Step 3 and Step 4 to point to this sequencing.
In
`@src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md`:
- Line 117: The phrase "feedback loop" used in the WRONG pattern at the line
containing "❌ WRONG: Multiple epics each modify the same core files with no
feedback loop between them" is undefined; add a concise definition of "feedback
loop" in step-02 (e.g., what constitutes a feedback loop: stakeholder review
gates, user acceptance testing, technical spikes, iterative design learnings, or
production customer feedback) and then update this step-04 line to reference
that definition (mention "see step-02 definition of 'feedback loop'") so
validators can distinguish justified epic splits from unjustified ones; ensure
you update the header or sentence in step-02 (the step-02 description ID or
title) and use that exact title when cross-referencing in step-04.
- Line 118: The RIGHT pattern text "Epics target distinct files/components, OR
consolidation was explicitly considered and rejected with rationale" is
ambiguous; update the rule to (1) define "component" (e.g.,
module/service/package/UI widget/namespace) and reference that definition, (2)
introduce an overlapThreshold (e.g., 10–20%) and require consolidationRationale
when shared-files between epics exceed that threshold, and (3) add a required
metadata field consolidationRationale (or a boolean consolidationConsidered +
rationale) to be populated whenever overlap >= overlapThreshold or when
consolidation was explicitly considered; change the pattern wording and any
validation logic to enforce these fields and threshold checks instead of the
current binary OR.
- Around line 113-118: File Churn Check is unexecutable because upstream
templates and thresholds are missing: extend the epics_list template
(epics_list) to capture an affected_files array and a consolidation_rationale
field, update step-03 story creation to populate affected_files for each epic
(so stories register file paths back to the epic), and add a concrete overlap
threshold definition in step-02 (e.g., overlap_threshold as either
min_shared_files or percent_shared_files) that step-04's File Churn Check
validator uses; finally modify the step-04 validation logic (File Churn Check)
to compute overlap using the new affected_files, compare against
overlap_threshold, and require consolidation_rationale when overlap exceeds the
threshold.
---
Outside diff comments:
In
`@src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md`:
- Around line 152-166: The epics_list template lacks a place to record overlap
analysis required by Step B/C and by final validation; update the epics_list
template to include explicit overlap annotation fields for each epic such as
"Overlap (files/percentage):", "Overlap reviewed: (yes/no)", and "Consolidation
decision & rationale:" so agents can record which files overlap, the measured
overlap percentage or list, whether the overlap was reviewed, and why
consolidation was accepted or rejected (this ties into Step B's "annotate with
considerations about overlap", Step C file-overlap review, and Step 4 in
step-04-final-validation.md).
- Around line 119-211: In Section 3 ("Design Epic Structure Collaboratively")
the sub-step labels are inconsistent: the document uses "Step A/B/C/D" for the
initial sub-steps (Step A: Assess Context..., Step B: Propose Epic Structure,
Step C: Review for File Overlap, Step D: Create the epics_list) but then
switches to numeric "4. Present Epic List for Review", "5. Create Requirements
Coverage Map", "6. Collaborative Refinement", "7. Get Final Approval"; unify the
hierarchy by choosing one convention and applying it consistently—either rename
Steps A-D to "Step 1/2/3/4" (or "4.1/4.2..." if 4–7 are siblings) or rename
numeric 4–7 to "Step E/F/G/H" (or "Step 3.E..." to indicate nesting), and ensure
headings show correct nesting (e.g., "###" level matches) so that references
like "Step A", "Step D: Create the epics_list", and "4. Present Epic List for
Review" consistently reflect their intended sibling/child relationship
throughout the section.
---
Nitpick comments:
In
`@src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md`:
- Around line 226-238: The menu handling branch "IF Any other comments or
queries: help user respond then [Redisplay Menu Options]" lacks error
boundaries; add a guard that tracks consecutive unrecognized inputs for the menu
handler (the "IF Any other comments or queries" flow) and after 3 consecutive
invalid responses present an escape prompt offering "[C]ontinue with current
epics, [R]evise epic structure, or [H]elp with menu options" (and an option to
escalate/exit), reset the invalid-input counter after a valid selection or
escalation, and ensure the execution rules (ALWAYS halt and wait; ONLY proceed
on 'C') still apply while preventing infinite redisplay loops by treating the
escape choices as explicit next actions.
In
`@src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md`:
- Around line 113-118: Add a cross-check between "File Churn Check" and
"Dependency Validation": when "File Churn Check" triggers consolidation (Step 2,
Step C), run an additional verification in the "Dependency Validation" step to
ensure the consolidated epic's story dependencies remain backward-only (no
forward dependencies introduced by merging Epic 2/Epic 3). Update the logic
around the File Churn Check outcome to pass a "consolidated" flag or list of
merged epics into Dependency Validation and, inside the Dependency Validation
flow, re-evaluate story dependency direction for any consolidated epic and
surface failures if forward dependencies exist.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 20d3f996-ec09-4777-8bea-794006c9b052
📒 Files selected for processing (2)
src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.mdsrc/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md
src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md
Show resolved
Hide resolved
src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md
Show resolved
Hide resolved
src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md
Show resolved
Hide resolved
src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md
Show resolved
Hide resolved
src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md
Show resolved
Hide resolved
src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md
Show resolved
Hide resolved
src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md
Show resolved
Hide resolved
src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md
Show resolved
Hide resolved
src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md
Show resolved
Hide resolved
src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md
Show resolved
Hide resolved
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.
What
Add brownfield-aware epic scoping to the Create Epics and Stories workflow, helping the AI agent detect and consolidate epics that repeatedly target the same core files.
Why
When applied to features targeting a single existing component, the epic design workflow produces multiple epics that cause unnecessary file churn — splitting implementation across epics that all modify the same files without the customer-feedback benefit that justifies incremental delivery.
Fixes #1823
How
Testing
Executed the modified workflow against my project with complete planning artifacts (Architecture, UX, PRD) targeting a single existing component. The resulting epic structure consolidated correctly into fewer epics compared to the unmodified workflow, which had previously split the same feature into multiple epics with redundant file modifications.
Out-of-scope (Open for discussion)
The story sizing language in step-03-create-stories.md still uses vague terms like "sized appropriately" and "single dev session" without anchoring to the actual constraint: a story must fit within a single dev agent's context window. This is out of scope for this PR but would strengthen the sizing signal.