From d0985170c978b6acf3c66747c609850e54413f68 Mon Sep 17 00:00:00 2001
From: Maple <hzlhu@qq.com>
Date: Sun, 15 Feb 2026 01:06:57 +0800
Subject: [PATCH] fix(create-story): clarify required vars and metadata prompt
 flow

---
 src/bmm/workflows/4-implementation/create-story/checklist.md | 5 ++++-
 .../workflows/4-implementation/create-story/instructions.xml | 2 +-
 src/core/tasks/validate-workflow.xml                         | 3 +--
 3 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/src/bmm/workflows/4-implementation/create-story/checklist.md b/src/bmm/workflows/4-implementation/create-story/checklist.md
index 545b0a7a1..0f5075e9f 100644
--- a/src/bmm/workflows/4-implementation/create-story/checklist.md
+++ b/src/bmm/workflows/4-implementation/create-story/checklist.md
@@ -68,7 +68,10 @@ You will systematically re-do the entire story creation process, but with a crit
    - Parse workflow.yaml key/value pairs
    - For any value matching `{config_source}:key`, load the referenced config file and resolve `key`
    - Resolve system path variables (for example `{project-root}`, `{installed_path}`) in every path value
-   - If any required variable remains unresolved, stop and request explicit user input before continuing
+   - Required for this checklist flow: `{default_output_file}`, `{epics_file}`, `{architecture_file}`, `{implementation_artifacts}`, `{project-root}`, `{installed_path}`
+   - Optional/fallback-capable values: `{story_file}`, validation `{checklist}` input, validation `{report}` input
+   - Validation task input contract: `workflow` is required; `checklist`, `document`, and `report` are optional with deterministic fallback
+   - If any required value remains unresolved, stop and request explicit user input before continuing
 5. **Extract metadata**: epic_num, story_num, story_key, story_title from story file
 6. **Understand current status**: What story implementation guidance is currently provided?
 
diff --git a/src/bmm/workflows/4-implementation/create-story/instructions.xml b/src/bmm/workflows/4-implementation/create-story/instructions.xml
index 0f3ef5b78..0612001de 100644
--- a/src/bmm/workflows/4-implementation/create-story/instructions.xml
+++ b/src/bmm/workflows/4-implementation/create-story/instructions.xml
@@ -306,7 +306,7 @@
   </step>
 
   <step n="6" goal="Update sprint status and finalize">
-    <invoke-task>Run _bmad/core/tasks/validate-workflow.xml with workflow={installed_path}/workflow.yaml checklist={installed_path}/checklist.md document={default_output_file}</invoke-task>
+    <invoke-task>Run {project-root}/_bmad/core/tasks/validate-workflow.xml with workflow={installed_path}/workflow.yaml checklist={installed_path}/checklist.md document={default_output_file}</invoke-task>
     <action>Save story document unconditionally</action>
 
     <!-- Update sprint status -->
diff --git a/src/core/tasks/validate-workflow.xml b/src/core/tasks/validate-workflow.xml
index 7db351faf..773115fe3 100644
--- a/src/core/tasks/validate-workflow.xml
+++ b/src/core/tasks/validate-workflow.xml
@@ -52,7 +52,7 @@
       <action>Determine critical checks from explicit signals only: item-level markers ([CRITICAL], critical:true, MUST FIX) or critical section labels; do not infer criticality from generic keywords alone</action>
       <action>Detect conditional expressions in checklist items (for example: if/when/unless + variable references)</action>
       <action if="no checklist items parsed">HALT with error: "Checklist is empty or unparsable"</action>
-      <action if="conditional items reference metadata and metadata is missing">Record metadata_gap=true and list missing metadata fields for explicit PARTIAL decisions in step 3</action>
+      <action if="conditional items reference metadata and metadata is missing">Ask user to provide missing metadata fields (epic_num, story_num, story_id/story_key) and WAIT before evaluating checklist items</action>
     </step>
 
     <step n="3" title="Validate Every Checklist Item" critical="true">
@@ -141,7 +141,6 @@
     <step n="5" title="Return Decision and Halt">
       <action>Present concise summary with counts and gate decision</action>
       <action>Provide report path</action>
-      <action if="metadata_gap=true">Call out missing metadata fields that caused PARTIAL results and how to supply them</action>
       <action if="critical failures exist">State clearly that workflow should not proceed until fixes are applied</action>
       <action>HALT and wait for user direction</action>
     </step>