BMAD-METHOD/src/bmm/workflows/4-implementation/revalidate-story/instructions.md

Revalidate Story - Verify Checkboxes Against Codebase Reality

The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml

Verify story_file parameter provided ❌ ERROR: story_file parameter required

Usage: /revalidate-story story_file=path/to/story.md /revalidate-story story_file=path/to/story.md fill_gaps=true HALT

Read COMPLETE story file: {{story_file}} Parse sections: Acceptance Criteria, Tasks/Subtasks, Definition of Done, Dev Agent Record

Extract story_key from filename (e.g., "2-7-image-file-handling")

Create backup of current checkbox state: Count currently checked items: - ac_checked_before = count of [x] in Acceptance Criteria - tasks_checked_before = count of [x] in Tasks/Subtasks - dod_checked_before = count of [x] in Definition of Done - total_checked_before = sum of above

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔍 STORY REVALIDATION STARTED ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Story:** {{story_key}} **File:** {{story_file}} **Mode:** {{#if fill_gaps}}Verify & Fill Gaps{{else}}Verify Only{{/if}}

Current State:

• Acceptance Criteria: {{ac_checked_before}}/{{ac_total}} checked
• Tasks: {{tasks_checked_before}}/{{tasks_total}} checked
• Definition of Done: {{dod_checked_before}}/{{dod_total}} checked
• Total: {{total_checked_before}}/{{total_items}} ({{pct_before}}%)

Action: Clearing all checkboxes and re-verifying against codebase... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🧹 Clearing all checkboxes to start fresh verification...

Use Edit tool to replace all [x] with [ ] in Acceptance Criteria section Use Edit tool to replace all [x] with [ ] in Tasks/Subtasks section Use Edit tool to replace all [x] with [ ] in Definition of Done section

Save story file with all boxes unchecked

✅ All checkboxes cleared. Starting verification from clean slate...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 VERIFYING ACCEPTANCE CRITERIA ({{ac_total}} items) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Extract all AC items from Acceptance Criteria section

For each AC item:

Extract AC description and identify artifacts: - File mentions (e.g., "UserProfile component") - Function names (e.g., "updateUser function") - Features (e.g., "dark mode toggle") - Test requirements (e.g., "unit tests covering edge cases")

<output>Verifying AC{{@index}}: {{ac_description}}</output>

Use Glob to find relevant files: - If AC mentions specific file: glob for that file - If AC mentions component: glob for **/*ComponentName* - If AC mentions feature: glob for files in related directories

<action>Use Grep to search for symbols/functions/features</action>

<action>Read found files to verify:</action>
<action>- NOT a stub (check for "TODO", "Not implemented", "throw new Error")</action>
<action>- Has actual implementation (not just empty function)</action>
<action>- Tests exist (search for *.test.* or *.spec.* files)</action>
<action>- Tests pass (if --fill-gaps mode, run tests)</action>

verification_status = VERIFIED Check box [x] in story file for this AC Record evidence: "✅ VERIFIED: {{files_found}}, tests: {{test_files}}" ✅ AC{{@index}}: VERIFIED

<check if="partial evidence OR stubs found OR tests missing">
  <action>verification_status = PARTIAL</action>
  <action>Check box [~] in story file for this AC</action>
  <action>Record gap: "🔶 PARTIAL: {{what_exists}}, missing: {{what_is_missing}}"</action>
  <output>  🔶 AC{{@index}}: PARTIAL ({{what_is_missing}})</output>
  <action>Add to gaps_list with details</action>
</check>

<check if="no evidence found">
  <action>verification_status = MISSING</action>
  <action>Leave box unchecked [ ] in story file</action>
  <action>Record gap: "❌ MISSING: No implementation found for {{ac_description}}"</action>
  <output>  ❌ AC{{@index}}: MISSING</output>
  <action>Add to gaps_list with details</action>
</check>

Save story file after each AC verification

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Acceptance Criteria Verification Complete ✅ Verified: {{ac_verified}} 🔶 Partial: {{ac_partial}} ❌ Missing: {{ac_missing}} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 VERIFYING TASKS ({{tasks_total}} items) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Extract all Task items from Tasks/Subtasks section

For each Task item (same verification logic as ACs):

Parse task description for artifacts Search codebase with Glob/Grep Read and verify (check for stubs, tests) Determine status: VERIFIED | PARTIAL | MISSING Update checkbox: [x] | [~] | [ ] Record evidence or gap Save story file

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Tasks Verification Complete ✅ Verified: {{tasks_verified}} 🔶 Partial: {{tasks_partial}} ❌ Missing: {{tasks_missing}} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 VERIFYING DEFINITION OF DONE ({{dod_total}} items) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Extract all DoD items from Definition of Done section

For each DoD item:

Parse DoD requirement: - "Type check passes" → Run type checker - "Unit tests 90%+ coverage" → Run coverage report - "Linting clean" → Run linter - "Build succeeds" → Run build - "All tests pass" → Run test suite

Execute verification for this DoD item

Check box [x] Record: "✅ VERIFIED: {{verification_result}}" Leave unchecked [ ] or partial [~] Record gap if applicable ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Definition of Done Verification Complete ✅ Verified: {{dod_verified}} 🔶 Partial: {{dod_partial}} ❌ Missing: {{dod_missing}} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Calculate overall completion: total_verified = ac_verified + tasks_verified + dod_verified total_partial = ac_partial + tasks_partial + dod_partial total_missing = ac_missing + tasks_missing + dod_missing total_items = ac_total + tasks_total + dod_total

verified_pct = (total_verified / total_items) × 100
completion_pct = ((total_verified + total_partial) / total_items) × 100

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 REVALIDATION SUMMARY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Story:** {{story_key}} **File:** {{story_file}}

Verification Results:

• ✅ Verified Complete: {{total_verified}}/{{total_items}} ({{verified_pct}}%)
• 🔶 Partially Complete: {{total_partial}}/{{total_items}}
• ❌ Missing/Incomplete: {{total_missing}}/{{total_items}}

Breakdown:

• Acceptance Criteria: {{ac_verified}}✅ {{ac_partial}}🔶 {{ac_missing}}❌ / {{ac_total}} total
• Tasks: {{tasks_verified}}✅ {{tasks_partial}}🔶 {{tasks_missing}}❌ / {{tasks_total}} total
• Definition of Done: {{dod_verified}}✅ {{dod_partial}}🔶 {{dod_missing}}❌ / {{dod_total}} total

Status Assessment: {{#if verified_pct >= 95}} ✅ Story is COMPLETE ({{verified_pct}}% verified) {{else if verified_pct >= 80}} 🔶 Story is MOSTLY COMPLETE ({{verified_pct}}% verified, {{total_missing}} gaps) {{else if verified_pct >= 50}} ⚠️ Story is PARTIALLY COMPLETE ({{verified_pct}}% verified, {{total_missing}} gaps) {{else}} ❌ Story is INCOMPLETE ({{verified_pct}}% verified, significant work missing) {{/if}}

Before Revalidation: {{total_checked_before}}/{{total_items}} checked ({{pct_before}}%) After Revalidation: {{total_verified}}/{{total_items}} verified ({{verified_pct}}%) Accuracy: {{#if pct_before == verified_pct}}Perfect match{{else if pct_before > verified_pct}}{{pct_before - verified_pct}}% over-reported{{else}}{{verified_pct - pct_before}}% under-reported{{/if}}

{{#if total_missing > 0}}

Gaps Found ({{total_missing}}): {{#each gaps_list}} {{@index + 1}}. {{item_type}} - {{item_description}} Status: {{status}} Missing: {{what_is_missing}} {{#if evidence}}Evidence checked: {{evidence}}{{/if}} {{/each}}

{{/if}} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Write detailed report to: {sprint_artifacts}/revalidation-{{story_key}}-{{timestamp}}.md Include: verification results, gaps list, evidence for each item, recommendations 📄 Detailed report: {{report_path}} ✅ Verification complete (verify-only mode)

{{#if total_missing > 0}} To fill the {{total_missing}} gaps, run: /revalidate-story story_file={{story_file}} fill_gaps=true {{else}} No gaps found - story is complete! {{/if}} Exit workflow

✅ No gaps to fill - story is already complete! Exit workflow ⚠️ TOO MANY GAPS: {{total_missing}} gaps found (max: {{max_gaps_to_fill}})

This story has too many missing items for automatic gap filling. Consider:

1. Re-implementing the story from scratch with /dev-story
2. Manually implementing the gaps
3. Increasing max_gaps_to_fill in workflow.yaml (use cautiously)

Gap filling HALTED for safety. HALT

<output>

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔧 GAP FILLING MODE ({{total_missing}} gaps to fill) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

<action>Continue to Step 8</action>

For each gap in gaps_list: Fill this gap?

Item: {{item_description}} Type: {{item_type}} ({{section}}) Missing: {{what_is_missing}}

[Y] Yes - Implement this item [A] Auto-fill - Implement this and all remaining gaps without asking [S] Skip - Leave this gap unfilled [H] Halt - Stop gap filling

Your choice:

  <check if="choice == 'A'">
    <action>Set require_confirmation = false (auto-fill remaining)</action>
  </check>

  <check if="choice == 'S'">
    <action>Continue to next gap</action>
  </check>

  <check if="choice == 'H'">
    <action>Exit gap filling loop</action>
    <action>Jump to Step 9 (Summary)</action>
  </check>
</check>

🔧 Implementing: {{item_description}}

<action>Load story context (Technical Requirements, Architecture Compliance, Dev Notes)</action>
<action>Implement missing item following story specifications</action>
<action>Write tests if required</action>
<action>Run tests to verify implementation</action>
<action>Verify linting/type checking passes</action>

<check if="implementation succeeds AND tests pass">
  <action>Check box [x] for this item in story file</action>
  <action>Update File List with new/modified files</action>
  <action>Add to Dev Agent Record: "Gap filled: {{item_description}}"</action>
  <output>  ✅ Implemented and verified</output>

  <check if="commit_strategy == 'per_gap'">
    <action>Stage files for this gap</action>
    <action>Commit: "fix({{story_key}}): fill gap - {{item_description}}"</action>
    <output>  ✅ Committed</output>
  </check>
</check>

<check if="implementation fails">
  <output>  ❌ Failed to implement: {{error_message}}</output>
  <action>Leave box unchecked</action>
  <action>Record failure in gaps_list</action>
  <action>Add to failed_gaps</action>
</check>

After all gaps processed: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Gap Filling Complete ✅ Filled: {{gaps_filled}} ❌ Failed: {{gaps_failed}} ⏭️ Skipped: {{gaps_skipped}} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔍 Re-verifying filled gaps...

<iterate>For each filled gap:</iterate>
<action>Re-run verification for that item</action>
<action>Ensure still VERIFIED after all changes</action>

<output>✅ All filled gaps re-verified</output>

Calculate final completion: final_verified = count of [x] across all sections final_partial = count of [~] across all sections final_missing = count of [ ] across all sections final_pct = (final_verified / total_items) × 100

Stage all changed files Commit: "fix({{story_key}}): fill {{gaps_filled}} gaps from revalidation" ✅ All gaps committed Load {sprint_status} file Update entry with current progress: Format: {{story_key}}: {{current_status}} # Revalidated: {{final_verified}}/{{total_items}} ({{final_pct}}%) verified Save sprint-status.yaml ✅ Sprint status updated with revalidation results Add to Dev Agent Record in story file: ## Revalidation Record ({{timestamp}})

Revalidation Mode: {{#if fill_gaps}}Verify & Fill{{else}}Verify Only{{/if}}

Results:

• Verified: {{final_verified}}/{{total_items}} ({{final_pct}}%)
• Gaps Found: {{total_missing}}
• Gaps Filled: {{gaps_filled}}

Evidence: {{#each verification_evidence}}

• {{item}}: {{evidence}} {{/each}}

{{#if gaps_filled > 0}} Gaps Filled: {{#each filled_gaps}}

• {{item}}: {{what_was_implemented}} {{/each}} {{/if}}

{{#if failed_gaps.length > 0}} Failed to Fill: {{#each failed_gaps}}

• {{item}}: {{error}} {{/each}} {{/if}} Save story file

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ REVALIDATION COMPLETE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Story:** {{story_key}}

Final Status:

• ✅ Verified Complete: {{final_verified}}/{{total_items}} ({{final_pct}}%)
• 🔶 Partially Complete: {{final_partial}}/{{total_items}}
• ❌ Missing/Incomplete: {{final_missing}}/{{total_items}}

{{#if fill_gaps}} Gap Filling Results:

• Filled: {{gaps_filled}}
• Failed: {{gaps_failed}}
• Skipped: {{gaps_skipped}} {{/if}}

Accuracy Check:

• Before revalidation: {{pct_before}}% checked
• After revalidation: {{final_pct}}% verified
• Checkbox accuracy: {{#if pct_before == final_pct}}✅ Perfect (0% discrepancy){{else if pct_before > final_pct}}⚠️ {{pct_before - final_pct}}% over-reported (checkboxes were optimistic){{else}}🔶 {{final_pct - pct_before}}% under-reported (work done but not checked){{/if}}

{{#if final_pct >= 95}} Recommendation: Story is COMPLETE - mark as "done" or "review" {{else if final_pct >= 80}} Recommendation: Story is mostly complete - finish remaining {{final_missing}} items then mark "review" {{else if final_pct >= 50}} Recommendation: Story has significant gaps - continue development with /dev-story {{else}} Recommendation: Story is mostly incomplete - consider re-implementing with /dev-story or /super-dev-pipeline {{/if}}

{{#if failed_gaps.length > 0}} ⚠️ Manual attention needed for {{failed_gaps.length}} items that failed to fill automatically {{/if}}

{{#if create_report}} Detailed Report: {sprint_artifacts}/revalidation-{{story_key}}-{{timestamp}}.md {{/if}} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━