fix(bmm): give bmad-code-review its own deferred-work-format copy (PATH-05)

The prior commit pointed bmad-code-review at bmad-quick-dev's
deferred-work-format.md via a relative path (`../bmad-quick-dev/...`), which
reaches across a skill boundary and violates the PATH-05 encapsulation rule
(tools/skill-validator.md) — fragile when the skills are installed
independently. Ship a local copy inside bmad-code-review and reference it
locally instead:

- add bmad-code-review/deferred-work-format.md (identical to bmad-quick-dev's,
  plus a one-line "keep the two in sync" note).
- automation-mode.md rule 7: reference `./deferred-work-format.md`.
- steps/step-04-present.md: reference `../deferred-work-format.md`.

bmad-quick-dev is unchanged. validate:skills / validate:refs / lint:md /
format:check all pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
pbean 2026-06-21 21:17:18 -07:00
parent 57261d4cf0
commit 3a5b471473
3 changed files with 64 additions and 3 deletions

View File

@ -66,8 +66,7 @@ this workflow.
`PREFERENCE` escalation so a human can revisit the call. `PREFERENCE` escalation so a human can revisit the call.
7. **Act** (step-04): write findings to the spec file as usual; apply EVERY 7. **Act** (step-04): write findings to the spec file as usual; apply EVERY
`patch` finding without asking; append `defer` findings to the `patch` finding without asking; append `defer` findings to the
deferred-work file following the format in the sibling `bmad-quick-dev` deferred-work file following the format in `./deferred-work-format.md`;
skill's deferred-work format file at `../bmad-quick-dev/deferred-work-format.md`;
skip the "Next steps" menu entirely. skip the "Next steps" menu entirely.
8. **Status updates** (step-04 section 6) run exactly as written: spec 8. **Status updates** (step-04 section 6) run exactly as written: spec
status (frontmatter `status:`) and sprint-status sync. status (frontmatter `status:`) and sprint-status sync.

View File

@ -0,0 +1,62 @@
# Deferred Work Format
Canonical entry format for `{implementation_artifacts}/deferred-work.md`.
Used (in `bmad-auto` automation mode) by bmad-quick-dev (multi-goal splits,
token splits, review defers) and bmad-code-review (defer findings). This copy
lives in the bmad-code-review skill; an identical copy ships with bmad-quick-dev
— keep the two in sync when the format changes. The file is append-only — never
rewrite or delete existing entries. (One exception: freeform pre-DW-format
content from older projects is rewritten wholesale into canonical entries by a
`bmad-auto sweep` migration run — an orchestrator-side process external to this
skill; the TUI displays such legacy items read-only until that happens.)
## Before appending: dedupe check
Scan the existing file for an entry describing the same issue or goal (same
location and same substance, even if worded differently). If one exists, do
NOT append a duplicate — add a `seen-again:` line to the existing entry
instead:
```markdown
seen-again: 2026-06-12 (code review of spec-3-3-export.md)
```
## Entry format
Number entries sequentially (`DW-1`, `DW-2`, …) by scanning the file for the
highest existing number. One entry per deferred item:
```markdown
### DW-<seq>: <one-line title>
origin: <workflow + artifact + date, e.g. "bmad-quick-dev split of spec-3-2-digest.md, 2026-06-12">
location: <file:line or component, or "n/a" for deferred goals>
severity: <critical | high | medium | low how much it matters if never done>
reason: <why this was deferred rather than done now, one or two sentences>
status: open
```
`severity:` is optional — entries written before this field existed have none
and that is fine; readers must treat a missing or unrecognized value as
"unspecified". Use `critical` for correctness/security issues, `high` for
likely user-visible problems, `medium` for quality and robustness gaps, `low`
for polish and nice-to-haves.
When a deferred item is later completed, set its `status:` to `done` with the
date (e.g. `status: done 2026-06-20`) — do not delete the entry.
## Sweep annotations
`bmad-auto sweep` runs (the orchestrator and its bundle dev sessions) add two
optional field lines to existing entries — both directly after `status:`:
```markdown
resolution: <one line: what was built or why the entry was closed>
decision: <date> <chosen option label><detail>
```
- `resolution:` accompanies every sweep close (`status: done <date>`). Bundle
dev sessions write it when finishing a bundle's entries; the orchestrator
writes it when closing entries triage proved already resolved.
- `decision:` records a human's sweep-time choice on an entry. It does not by
itself change `status:` — a `keep-open` decision leaves the entry open.

View File

@ -43,7 +43,7 @@ If `{spec_file}` exists and contains a Tasks/Subtasks section, append a `### Rev
Also append each `defer` finding to `{deferred_work_file}` under a heading `## Deferred from: code review ({date})`. If `{spec_file}` is set, include its basename in the heading (e.g., `code review of story-3.3 (2026-03-18)`). One bullet per finding with description. Also append each `defer` finding to `{deferred_work_file}` under a heading `## Deferred from: code review ({date})`. If `{spec_file}` is set, include its basename in the heading (e.g., `code review of story-3.3 (2026-03-18)`). One bullet per finding with description.
**If `{auto_mode}`:** instead of the heading-based append above, append each `defer` finding to `{deferred_work_file}` as a `DW-<seq>` entry following the format and dedupe rule in the sibling `bmad-quick-dev` skill's deferred-work format file at `../../bmad-quick-dev/deferred-work-format.md`. Use `origin: code review of <spec basename>, {date}`, and set the entry's `severity:` from the finding's own severity. Then append a `#### Review Ledger ({date})` subsection to `{spec_file}` recording every triaged finding on one line each — `<verdict>: <title> [<location>] — <one-line reason>` — including the dismissed ones set aside in step-03. The ledger is append-only across review cycles; it is what stops the next cycle's fresh reviewers from re-litigating findings that were already adjudicated. **If `{auto_mode}`:** instead of the heading-based append above, append each `defer` finding to `{deferred_work_file}` as a `DW-<seq>` entry following the format and dedupe rule in `../deferred-work-format.md` (this skill's own copy). Use `origin: code review of <spec basename>, {date}`, and set the entry's `severity:` from the finding's own severity. Then append a `#### Review Ledger ({date})` subsection to `{spec_file}` recording every triaged finding on one line each — `<verdict>: <title> [<location>] — <one-line reason>` — including the dismissed ones set aside in step-03. The ledger is append-only across review cycles; it is what stops the next cycle's fresh reviewers from re-litigating findings that were already adjudicated.
### 3. Present summary ### 3. Present summary