BMAD #2767 — The Bug That Deleted Requirements Without a Trace
A framework silently deleted design requirements. We proved it upstream — and proposed the check that can’t be talked out of its verdict.
- •Found on a live enterprise delivery: the framework’s planner compiled epic context that dropped every reference to the 28 KB design contract — behaviour kept, filenames and tokens gone
- •Triage could not reproduce it — a precise fact package (version, model, artifacts with zero design refs) turned “works for me” into a maintainer-confirmed bug
- •Closed as tracked, not unresolved: proper backlinking became a v7 requirement, with the diagnosis recorded verbatim in the closing comment and both reporters credited
- •Independently confirmed and widened by a second team on a newer version — the thread spawned a sibling issue (#2796)
- •Proposed the v7 detector: a deterministic zero-hit grep with no model in it
- •Shipped our own stopgap meanwhile — measured, not assumed: it came with its own positive control
Tap to enlargeBMAD-METHOD is an open-source agentic delivery framework: planning artifacts in, epics and stories out, implementing agents at the end. Using it on a live enterprise delivery, the UI kept arriving subtly wrong — button misplaced, styling improvised, icon redrawn — while every generated document read as finished. The cause, found together with a colleague, was upstream: the framework’s context-compile step silently dropped every reference to the design contract, so the implementing agent never saw the visual rules it was supposed to follow. I filed it as issue #2767 with the failure mechanism analysed — and nine days later it closed as a confirmed bug and a v7 requirement, with the diagnosis recorded verbatim in the maintainer’s closing comment. The stakes are the whole reason the framework exists: the pipeline turns out a feature’s artifacts in roughly twenty minutes, where building the same thing by hand takes days — and a silently dropped contract sends days of hand-rework straight back into that loop. The thread is public; every claim below can be checked against it.
Three Sensible Rules, One Silent Deletion
The dangerous loss is the one that leaves the text still reading fine
The compile step that condenses planning artifacts follows three rules: describe by purpose rather than source, never quote source documents, and stay inside a token budget. Each is sensible alone. Together — as the maintainer’s closing comment put it, recording the diagnosis — they delete any requirement that exists only as a pointer to a large file, with no signal in the output that anything was dropped.
Our epics file carried around forty anchored links into a 28 KB design contract, under the convention “single source of truth, do not restate tokens here”. The compiled context kept the behaviour and dropped every filename and token. The implementing agent then built the UI without ever seeing the visual contract — and because the output looked finished, the gap only surfaced when someone compared the result with the design by hand.
“Works For Me” Is Where Bug Reports Go to Die
Facts the other side can check beat files you cannot share
A maintainer confirmed the bug in principle the same morning. Then triage did the right thing and tried to break the claim: a minimal repro on current main survived, and so did a rerun with the design file grown to 38 KB. Two clean runs against our report — and the client files behind our case could not be attached.
What resolves that standoff is not insistence, it is facts the other side can check: the exact version (installed pre-rename, with the old hard rule still in the prompt), the exact model and date per story, which compiled artifacts contained zero design references, and the answer to triage’s sharpest question — the pointer was being lost twice, once in the compile step and once more in the planner that fails to restore it from the epics file. Client name tokenised throughout; nothing shared that should not be.
The issue closed as tracked rather than unresolved: proper backlinking during planning is now a v7 requirement, and the closing comment credits the diagnosis by name.
A Good Bug Report Keeps Working After It Closes
Two teams, two versions, one mechanism — confirmed from both directions
Hours after the close, a second team reported the same loss independently on a newer version — and widened it: constraints stated once inline get dropped the same way, and a cache-regeneration quirk multiplies the loss. Their correction also caught something that mattered for anyone following the thread’s stopgap advice: the override mechanism works when installed project-side and is silently inert user-side. That became sibling issue #2796.
Our reply added the positive control from the other direction — our install is project-side, both overrides engage — plus a measured boundary of the stopgap itself: a story planned five days after the fix went in still lacked the design files in its context, so the override reaches the implementing agent but not the planner. A workaround you have not measured is a wish.
The Detector Has No Model In It
Nothing generated gets trusted on faith — verify with a method the model is not part of
The fix proposal that went upstream is deliberately boring: after compiling, grep the output for every file the source anchors by name. A file referenced forty times that appears zero times in the compiled context is a failed compile, not a stylistic choice. Deterministic, milliseconds, and impossible to talk out of its verdict — because the model that generated the text is not part of the check.
That is the same principle behind the evaluation and design-verification work elsewhere in this portfolio, applied this time to the delivery framework itself: nothing generated gets trusted on faith, and the best verification is a method the generator cannot charm.
Interested in building something similar?
Let's Connect