refactor: replace 'execute' with 'Read fully and follow:' in workflow prompts#1387
Conversation
… prompts Replace ambiguous "execute" terminology with explicit "Read fully and follow:" phrasing across all workflow files to prevent LLM goal-seeking behavior where models attempt to "achieve the end result" rather than following step-by-step instructions verbatim. Changes: - Update 5 handler templates with canonical phrasing - Replace ~150 INSTRUCTIONAL patterns across 87 workflow files - Add "[Workflow] complete." prefix to 7 workflow endpoints - Preserve BEHAVIORAL/STRUCTURAL patterns (agent descriptions, XML tags) - Fix gitignore and markdownlint to ignore all node_modules directories Closes bmad-code-org#1372 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
alexeyv
force-pushed
the
refactor/replace-execute-with-read-follow
branch
from
82b8040 to
43508ef
Compare
|
@CodeRabbit review |
✅ Actions performedReview triggered.
|
📝 WalkthroughWalkthroughThis PR systematically replaces "execute" terminology with "read fully and follow" across workflow steps, instructions, and agent handler components to clarify LLM instructions for prompt file references. Changes span configuration files, documentation, multiple workflow directories, and utility components without altering underlying control flow. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related issues
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)
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: 5
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/2-plan-workflows/prd/steps-e/step-e-04-complete.md (1)
106-106: Replace “Execute” wording in menu option to match read‑follow directive.Line 106 reintroduces “Execute”, which contradicts the PR’s goal of removing that wording in prompt references.
Proposed fix
-**[V] Run Full Validation** - Execute complete validation workflow (steps-v) to verify PRD quality +**[V] Run Full Validation** - Read fully and follow the validation workflow (steps-v) to verify PRD qualitysrc/bmm/workflows/2-plan-workflows/prd/steps-c/step-08-scoping.md (1)
226-226: Align next-step wording with read‑follow model.Line 226 says “load {nextStepFile}” while the menu logic uses “read fully and follow,” which is inconsistent inside the same step.
Proposed fix
-After user selects 'C' and content is saved to document, load {nextStepFile}. +After user selects 'C' and content is saved to document, read fully and follow: {nextStepFile}.
🤖 Fix all issues with AI agents
In `@src/bmm/workflows/2-plan-workflows/prd/steps-e/step-e-02-review.md`:
- Line 223: The reference {partyModeWorkflow} is undefined in this file; either
add a frontmatter key named partyModeWorkflow with the canonical path (e.g.,
'{project-root}/_bmad/core/workflows/party-mode/workflow.md') alongside existing
keys like advancedElicitationTask, or replace the inline `{partyModeWorkflow}`
usage on the line "IF P: Read fully and follow: {partyModeWorkflow}, then return
to discussion" with the explicit path used across other workflow files
('{project-root}/_bmad/core/workflows/party-mode/workflow.md') so the link
resolves correctly.
In
`@src/bmm/workflows/2-plan-workflows/prd/steps-v/step-v-03-density-validation.md`:
- Line 151: Update the auto-proceed phrasing in the validation step files to
match the canonical urgency text used elsewhere: replace the existing "read
fully and follow:" instances in step-v-02b-parity-check.md and
step-v-02-format-detection.md with "Without delay, read fully and follow:
{nextStepFile}" so they match the wording used in
step-v-03-density-validation.md (the auto-proceed line). Ensure the exact token
"Without delay, read fully and follow: {nextStepFile}" is used so all steps in
the steps-v/ folder are consistent.
In
`@src/bmm/workflows/2-plan-workflows/prd/steps-v/step-v-08-domain-compliance-validation.md`:
- Line 164: Two identical progression lines use inconsistent formatting: one
uses {nextStepFile} alone (at the first occurrence) while the other appends the
explicit filename "(step-v-09-project-type-validation.md)"; update them to be
consistent. Locate the two occurrences that read "Without delay, read fully and
follow: {nextStepFile}" and either append the explicit filename to the first
occurrence so both read "{nextStepFile} (step-v-09-project-type-validation.md)"
or remove the parenthetical from the second occurrence so both use only
"{nextStepFile}"; ensure the variable {nextStepFile} remains unchanged.
In `@src/bmm/workflows/2-plan-workflows/prd/steps-v/step-v-13-report-complete.md`:
- Line 184: The relative link "steps-e/step-e-01-discovery.md" in
step-v-13-report-complete.md is wrong (it points into a non-existent
subdirectory of steps-v); update that reference to the sibling directory by
changing it to "../steps-e/step-e-01-discovery.md" so the "If yes: Read fully
and follow: ..." line correctly resolves to the steps-e step.
In `@src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md`:
- Line 144: The header "**[r]**: Execute Adversarial Review:" contains the
disallowed word "Execute"; change it to the preferred phrasing by replacing that
header with either "**[r]**: Adversarial Review:" or "**[r]**: Perform
Adversarial Review:" (pick one for consistency with the PR objective) so the
section uses "read fully and follow"/action-consistent terminology.
🧹 Nitpick comments (9)
src/bmm/workflows/2-plan-workflows/prd/steps-v/step-v-10-smart-validation.md (1)
24-24: Consider aligning terminology with the new "read fully and follow" pattern.The protocol descriptions at lines 24 and 49 still use "loading"/"load" terminology, while line 182 implements the transition with the new "read fully and follow" pattern. Given this PR's objective to standardize terminology and prevent LLM confusion, these references should probably use consistent phrasing.
♻️ Suggested terminology alignment
Line 24:
- 🔄 CRITICAL: When advancing to next step with 'C', ensure entire file is read fully firstLine 49:
- 📖 Display "Proceeding to next check..." and read fully and follow next stepAlso applies to: 49-49
src/bmm/workflows/2-plan-workflows/prd/steps-v/step-v-08-domain-compliance-validation.md (1)
76-84: Pre-existing section numbering issue.The sequence has duplicate "### 2." headers (lines 76 and 84), and step 4 is missing from the sequence (it jumps from step 3 to step 5). While this doesn't affect the PR changes, it may cause confusion when following the mandatory sequence.
Consider renumbering for clarity:
- Line 84: Change "### 2. Determine Domain Complexity" to "### 3. Determine Domain Complexity"
- Line 100: Update "### 3." to "### 4."
- Adjust subsequent step numbers accordingly
src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md (1)
60-62: Consider updating "Load" for consistency.For full consistency with the refactoring pattern applied at lines 175-177, consider updating these workflow routing instructions from "Load
{file}" to "Read fully and follow:{file}". While "Load" is less ambiguous than "execute", using the same phrasing throughout would reinforce the pattern and eliminate any potential interpretation variance.♻️ Proposed consistency update
- `[1]` → Read fully and follow: `{nextStepFile}` (Step 2) - `[1, 2]` → Read fully and follow: `{skipToStepFile}` (Step 3) - `[1, 2, 3]` → Read fully and follow: `./step-04-review.md` (Step 4)src/utility/agent-components/handler-workflow.txt (1)
7-7: Consider using canonical "Read fully and follow" phrasing.While this change replaces "Execute" with "Follow," the PR's stated canonical phrasing is "Read fully and follow:" (used across 150+ patterns). Consider whether this handler instruction should use the full canonical form for consistency, or if this abbreviated form is intentionally different for handler contexts.
src/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md (2)
22-22: Consider renaming the principle to match the new terminology.The principle is still named "Just-In-Time Loading" but the description now uses "loaded and followed to completion" which aligns with the new read-and-follow pattern. For consistency with the PR's objective to replace execution terminology, consider renaming this to something like "Just-In-Time Reading" or "Sequential Following" to better reflect the read-then-follow semantics.
♻️ Suggested terminology alignment
-- **Just-In-Time Loading**: Only 1 current step file will be loaded and followed to completion - never load future step files until told to do so +- **Just-In-Time Reading**: Only 1 current step file will be read and followed to completion - never read future step files until told to do so
34-34: Align the rule label with the new terminology.The rule label is "LOAD NEXT" but the instruction uses "read fully and follow the next step file". For consistency with the PR's terminology changes, consider updating the label to match the instruction semantics.
♻️ Suggested label alignment
-6. **LOAD NEXT**: When directed, read fully and follow the next step file +6. **READ NEXT**: When directed, read fully and follow the next step filesrc/bmm/workflows/1-analysis/create-product-brief/steps/step-01-init.md (1)
144-144: Minor inconsistency in variable formatting.Line 144 references
{nextStepFile}without backticks, while line 153 wraps the same variable reference in backticks:`{nextStepFile}`. For consistency across the document, consider using the same formatting style for all variable references.Suggested fix for consistency
Choose one style and apply consistently:
Option 1: No backticks (matches line 144)
ONLY WHEN [setup completion is achieved and frontmatter properly updated], will you then read fully and follow: {nextStepFile} to begin product vision discovery.Option 2: With backticks (matches line 153)
- After setup report is presented, without delay, read fully and follow: `{nextStepFile}`Also applies to: 153-153
src/utility/agent-components/handler-exec.txt (1)
3-4: Inconsistent phrasing pattern with other workflow files.The handler instructions use "Read fully and follow the file at that path" (line 3) and "Process the complete file and follow all instructions within it" (line 4), which differs from the canonical pattern established across other workflow files in this PR: "Read fully and follow: {path}".
Differences observed:
- Line 3: No colon after "follow" (other files use "Read fully and follow: {path}")
- Line 4: Uses "Process" instead of "Read"
For consistency with the broader PR changes, consider aligning this handler's phrasing with the canonical pattern.
Suggested alignment with canonical pattern
<handler type="exec"> When menu item or handler has: exec="path/to/file.md": 1. Read fully and follow: the file at that path 2. Follow all instructions within it completely 3. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context. </handler>src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-05-inspiration.md (1)
33-34: Inconsistent variable/path formatting within the file.The file uses inconsistent backtick formatting for path references:
- Lines 33-34, 182, 190: Paths without backticks (e.g.,
{project-root}/_bmad/core/workflows/...)- Line 200: Path with backticks (
`./step-06-design-system.md`)For consistency, consider using the same formatting style for all path references throughout the file.
Suggested fix for consistency
Option 1: Add backticks to all path references
- When 'A' selected: Read fully and follow: `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml` - When 'P' selected: Read fully and follow: `{project-root}/_bmad/core/workflows/party-mode/workflow.md`And similarly for lines 182 and 190.
Option 2: Remove backticks from line 200
- Read fully and follow: ./step-06-design-system.mdAlso applies to: 182-182, 190-190, 200-200
| - IF A: Execute {advancedElicitationTask}, then return to discussion | ||
| - IF P: Execute {partyModeWorkflow}, then return to discussion | ||
| - IF A: Read fully and follow: {advancedElicitationTask}, then return to discussion | ||
| - IF P: Read fully and follow: {partyModeWorkflow}, then return to discussion |
There was a problem hiding this comment.
Undefined variable reference: {partyModeWorkflow}
Line 223 references {partyModeWorkflow}, but this variable is not defined in the frontmatter (lines 1-11). Other similar workflow files use an explicit path like {project-root}/_bmad/core/workflows/party-mode/workflow.md or define the variable in frontmatter.
🔧 Proposed fix
Option 1: Add the variable to frontmatter:
| - IF P: Read fully and follow: {partyModeWorkflow}, then return to discussion | |
| advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' | |
| partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' |
Option 2: Use explicit path (consistent with other files):
| - IF P: Read fully and follow: {partyModeWorkflow}, then return to discussion | |
| - IF P: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md, then return to discussion |
🤖 Prompt for AI Agents
In `@src/bmm/workflows/2-plan-workflows/prd/steps-e/step-e-02-review.md` at line
223, The reference {partyModeWorkflow} is undefined in this file; either add a
frontmatter key named partyModeWorkflow with the canonical path (e.g.,
'{project-root}/_bmad/core/workflows/party-mode/workflow.md') alongside existing
keys like advancedElicitationTask, or replace the inline `{partyModeWorkflow}`
usage on the line "IF P: Read fully and follow: {partyModeWorkflow}, then return
to discussion" with the explicit path used across other workflow files
('{project-root}/_bmad/core/workflows/party-mode/workflow.md') so the link
resolves correctly.
| **Proceeding to next validation check...**" | ||
|
|
||
| Immediately load and execute {nextStepFile} (step-v-04-brief-coverage-validation.md) | ||
| Without delay, read fully and follow: {nextStepFile} (step-v-04-brief-coverage-validation.md) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for variations in "read fully and follow" phrasing across markdown files
rg -n "read fully and follow" --type mdRepository: bmad-code-org/BMAD-METHOD
Length of output: 12621
Standardize urgency phrasing within validation steps for consistency.
The validation steps (steps-v/) have inconsistent phrasing: most use "Without delay, read fully and follow:", but step-v-02b-parity-check.md and step-v-02-format-detection.md use only "read fully and follow:" without the urgency prefix. Standardize these to use the same phrasing throughout all validation step auto-proceed sections.
🤖 Prompt for AI Agents
In
`@src/bmm/workflows/2-plan-workflows/prd/steps-v/step-v-03-density-validation.md`
at line 151, Update the auto-proceed phrasing in the validation step files to
match the canonical urgency text used elsewhere: replace the existing "read
fully and follow:" instances in step-v-02b-parity-check.md and
step-v-02-format-detection.md with "Without delay, read fully and follow:
{nextStepFile}" so they match the wording used in
step-v-03-density-validation.md (the auto-proceed line). Ensure the exact token
"Without delay, read fully and follow: {nextStepFile}" is used so all steps in
the steps-v/ folder are consistent.
| **Proceeding to next validation check...**" | ||
|
|
||
| Immediately load and execute {nextStepFile} | ||
| Without delay, read fully and follow: {nextStepFile} |
There was a problem hiding this comment.
Inconsistent explicit filename reference between identical workflow progressions.
Both lines progress to the same next step using {nextStepFile}, but line 216 adds an explicit filename clarification (step-v-09-project-type-validation.md) while line 164 does not. Since both branches auto-proceed to the same target step, they should use consistent formatting.
Either add the explicit filename to line 164 for consistency, or remove it from line 216 since the variable {nextStepFile} already contains this value (defined at line 6).
Proposed fix for consistency
Option 1: Add explicit filename to both (recommended for clarity):
| Without delay, read fully and follow: {nextStepFile} | |
| Without delay, read fully and follow: {nextStepFile} (step-v-09-project-type-validation.md) |
Option 2: Remove explicit filename from line 216:
| Without delay, read fully and follow: {nextStepFile} | |
| Without delay, read fully and follow: {nextStepFile} |
Also applies to: 216-216
🤖 Prompt for AI Agents
In
`@src/bmm/workflows/2-plan-workflows/prd/steps-v/step-v-08-domain-compliance-validation.md`
at line 164, Two identical progression lines use inconsistent formatting: one
uses {nextStepFile} alone (at the first occurrence) while the other appends the
explicit filename "(step-v-09-project-type-validation.md)"; update them to be
consistent. Locate the two occurrences that read "Without delay, read fully and
follow: {nextStepFile}" and either append the explicit filename to the first
occurrence so both read "{nextStepFile} (step-v-09-project-type-validation.md)"
or remove the parenthetical from the second occurrence so both use only
"{nextStepFile}"; ensure the variable {nextStepFile} remains unchanged.
| - Explain: "The Edit workflow (steps-e/) can use this validation report to systematically address issues. Edit mode will guide you through discovering what to edit, reviewing the PRD, and applying targeted improvements." | ||
| - Offer: "Would you like to launch Edit mode now? It will help you fix validation findings systematically." | ||
| - If yes: Load and execute steps-e/step-e-01-discovery.md | ||
| - If yes: Read fully and follow: steps-e/step-e-01-discovery.md |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify the Edit workflow step path from the validation step location
# Find the current file
current_file="src/bmm/workflows/2-plan-workflows/prd/steps-v/step-v-13-report-complete.md"
# Check if the referenced path exists relative to current file's directory
echo "=== Checking relative path from steps-v/ ==="
if [ -f "src/bmm/workflows/2-plan-workflows/prd/steps-v/steps-e/step-e-01-discovery.md" ]; then
echo "✓ Path exists at: steps-v/steps-e/step-e-01-discovery.md"
else
echo "✗ Path does NOT exist at: steps-v/steps-e/step-e-01-discovery.md"
fi
# Check if the file exists as a sibling directory
echo ""
echo "=== Checking sibling directory path ==="
if [ -f "src/bmm/workflows/2-plan-workflows/prd/steps-e/step-e-01-discovery.md" ]; then
echo "✓ Path exists at: prd/steps-e/step-e-01-discovery.md (requires '../steps-e/' path)"
else
echo "✗ Path does NOT exist at: prd/steps-e/step-e-01-discovery.md"
fi
# List actual steps-e directory locations
echo ""
echo "=== Finding all steps-e directories ==="
fd -t d "^steps-e$" src/bmm/workflows/2-plan-workflows/
# Also check what's actually in the prd directory
echo ""
echo "=== Contents of prd directory ==="
ls -la src/bmm/workflows/2-plan-workflows/prd/
# Check what's in steps-v directory
echo ""
echo "=== Contents of steps-v directory ==="
ls -la src/bmm/workflows/2-plan-workflows/prd/steps-v/Repository: bmad-code-org/BMAD-METHOD
Length of output: 2302
Fix the relative path to the Edit workflow step.
The relative path steps-e/step-e-01-discovery.md is incorrect. It would resolve to a non-existent subdirectory within steps-v/. Since steps-e/ is a sibling directory of steps-v/ under prd/, the path should be ../steps-e/step-e-01-discovery.md.
🤖 Prompt for AI Agents
In `@src/bmm/workflows/2-plan-workflows/prd/steps-v/step-v-13-report-complete.md`
at line 184, The relative link "steps-e/step-e-01-discovery.md" in
step-v-13-report-complete.md is wrong (it points into a non-existent
subdirectory of steps-v); update that reference to the sibling directory by
changing it to "../steps-e/step-e-01-discovery.md" so the "If yes: Read fully
and follow: ..." line correctly resolves to the steps-e step.
| - **[d]**: Exit workflow - display final confirmation and path to spec | ||
| - **[p]**: Load and execute `{party_mode_exec}`, then return here and redisplay menu | ||
| - **[p]**: Read fully and follow: `{party_mode_exec}`, then return here and redisplay menu | ||
| - **[r]**: Execute Adversarial Review: |
There was a problem hiding this comment.
Inconsistent terminology: "Execute" still present in section header.
Line 144 uses "Execute Adversarial Review:" which contradicts the PR objective to replace "execute" with "read fully and follow" terminology. This appears to be a missed occurrence.
📝 Suggested fix for consistency
| - **[r]**: Execute Adversarial Review: | |
| - **[r]**: Execute Adversarial Review: | |
| + **[r]**: Adversarial Review: |
Or if you prefer to maintain the action-oriented pattern:
| - **[r]**: Execute Adversarial Review: | |
| - **[r]**: Execute Adversarial Review: | |
| + **[r]**: Perform Adversarial Review: |
🤖 Prompt for AI Agents
In `@src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md` at line
144, The header "**[r]**: Execute Adversarial Review:" contains the disallowed
word "Execute"; change it to the preferred phrasing by replacing that header
with either "**[r]**: Adversarial Review:" or "**[r]**: Perform Adversarial
Review:" (pick one for consistency with the PR objective) so the section uses
"read fully and follow"/action-consistent terminology.
2 participants
Summary
**/node_modules/**directoriesChanges
Test plan
Closes #1372
🤖 Generated with Claude Code