From 3a5b471473be5d4745d7ae90f7a9ce852dfbb5a2 Mon Sep 17 00:00:00 2001 From: pbean Date: Sun, 21 Jun 2026 21:17:18 -0700 Subject: [PATCH] fix(bmm): give bmad-code-review its own deferred-work-format copy (PATH-05) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../bmad-code-review/automation-mode.md | 3 +- .../bmad-code-review/deferred-work-format.md | 62 +++++++++++++++++++ .../bmad-code-review/steps/step-04-present.md | 2 +- 3 files changed, 64 insertions(+), 3 deletions(-) create mode 100644 src/bmm-skills/4-implementation/bmad-code-review/deferred-work-format.md diff --git a/src/bmm-skills/4-implementation/bmad-code-review/automation-mode.md b/src/bmm-skills/4-implementation/bmad-code-review/automation-mode.md index 5bc7cbf0a..7062c0f2c 100644 --- a/src/bmm-skills/4-implementation/bmad-code-review/automation-mode.md +++ b/src/bmm-skills/4-implementation/bmad-code-review/automation-mode.md @@ -66,8 +66,7 @@ this workflow. `PREFERENCE` escalation so a human can revisit the call. 7. **Act** (step-04): write findings to the spec file as usual; apply EVERY `patch` finding without asking; append `defer` findings to the - deferred-work file following the format in the sibling `bmad-quick-dev` - skill's deferred-work format file at `../bmad-quick-dev/deferred-work-format.md`; + deferred-work file following the format in `./deferred-work-format.md`; skip the "Next steps" menu entirely. 8. **Status updates** (step-04 section 6) run exactly as written: spec status (frontmatter `status:`) and sprint-status sync. diff --git a/src/bmm-skills/4-implementation/bmad-code-review/deferred-work-format.md b/src/bmm-skills/4-implementation/bmad-code-review/deferred-work-format.md new file mode 100644 index 000000000..86f400930 --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-code-review/deferred-work-format.md @@ -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-: + +origin: +location: +severity: +reason: +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: +decision: — +``` + +- `resolution:` accompanies every sweep close (`status: done `). 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. diff --git a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md index 8c57cf849..dc1627865 100644 --- a/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md +++ b/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md @@ -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. -**If `{auto_mode}`:** instead of the heading-based append above, append each `defer` finding to `{deferred_work_file}` as a `DW-` 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 , {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 — `: [<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