From c29b72ecc0177f98658eaa3233e5a4fbf47b8c9b Mon Sep 17 00:00:00 2001
From: Pablo Ontiveros <pablo.ontiveros@gmail.com>
Date: Sat, 25 Apr 2026 01:21:10 +0200
Subject: [PATCH] fix(create-story): read UPDATE files before generating dev
 notes (#2274)

When a story modifies existing files, create-story must read those
files before generating dev notes. Without this, dev agents improvise
design decisions without knowing the current state of the code, leading
to regressions caught only at review time.

Adds a step at the end of Step 3 (Architecture analysis) that reads
every file marked UPDATE in the architecture directory structure and
documents its current state, what the story changes, and what must
be preserved.

Fixes #2273

Co-authored-by: Brian Madison <bmadcode@gmail.com>
---
 .../4-implementation/bmad-create-story/SKILL.md      | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/bmm-skills/4-implementation/bmad-create-story/SKILL.md b/src/bmm-skills/4-implementation/bmad-create-story/SKILL.md
index b746b9f57..cf14039c1 100644
--- a/src/bmm-skills/4-implementation/bmad-create-story/SKILL.md
+++ b/src/bmm-skills/4-implementation/bmad-create-story/SKILL.md
@@ -302,6 +302,18 @@ Activation is complete. Begin the workflow below.
   processes - **Integration Patterns:** External service integrations, data flows <action>Extract any story-specific requirements that the
   developer MUST follow</action>
   <action>Identify any architectural decisions that override previous patterns</action>
+
+  <!-- Read existing code being modified — non-negotiable -->
+  <critical>📂 READ FILES BEING MODIFIED — skipping this is the primary cause of implementation failures and review cycles</critical>
+  <action>From the architecture directory structure, identify every file marked UPDATE (not NEW) that this story will touch</action>
+  <action>Read each relevant UPDATE file completely. For each one, document in dev notes:
+    - Current state: what it does today (state machine, API calls, data shapes, existing behaviors)
+    - What this story changes: the specific sections or behaviors being modified
+    - What must be preserved: existing interactions and behaviors the story must not break
+  </action>
+  <critical>A story implementation must leave the system working end-to-end — not just satisfy its stated ACs.
+  If a behavior is required for the feature to work correctly in the existing system, it is a requirement
+  whether or not it is explicitly written in the story. The dev agent owns this.</critical>
 </step>
 
 <step n="4" goal="Web research for latest technical specifics">