#6272·beads

bd update --notes help reads as additive while the flag replaces the field

Author: dsentCreated Sep 4, 2026Updated Sep 16, 2026

bd update --help calls --notes "Additional notes", and the prime text injected into every session lists it as "Add supplementary notes". Both read as appending, so an agent following the injected guidance faithfully destroys prior context.

I observed this multiple times with Claude Code and Codex — silently overwriting important notes when they need to add extra information, so I have to fish them out of the history later.

--design, and --description behave similarly, but their descriptions are more accurate:

--append-notes string      Append to existing notes (with newline separator)
--notes string             Additional notes
-d, --description string   Issue description
--design string            Design notes

"Additional" is the only word separating the two descriptions, and it points at the wrong one. --description and --design are named for their fields and imply nothing about merge behavior, so --notes is the single misleading entry in the group.

Proposed solution

A help string that names the operation rather than the field, so the contrast with --append-notes is visible at the point of use — for example Replace the notes field (--append-notes adds to it).