From ffada07c94e5c40c834da89d6d06d9c6612dbdb0 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Fri, 7 Aug 2026 11:42:31 -0700 Subject: [PATCH] docs(project-context): fold in prior-art research findings Five adoptions from the generator prior-art survey: prohibitions name their permitted alternative; an emphasis-marker budget; a git-log --diff-filter=DR drift check on refresh; TODO placeholders over guessed greenfield commands; commit and branch conventions mined from history. --- src/bmm-skills/plan/bmad-project-context/SKILL.md | 4 ++-- .../plan/bmad-project-context/references/evidence.md | 2 +- .../plan/bmad-project-context/references/guide-contract.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/bmm-skills/plan/bmad-project-context/SKILL.md b/src/bmm-skills/plan/bmad-project-context/SKILL.md index 0faff7dcd..685733e15 100644 --- a/src/bmm-skills/plan/bmad-project-context/SKILL.md +++ b/src/bmm-skills/plan/bmad-project-context/SKILL.md @@ -34,9 +34,9 @@ Load `references/guide-contract.md` and `references/evidence.md` before step 1. 5. **Compose.** Decide what each section says from the accepted candidates, then write the guide as one coherent document under the contract. Copy-editing comes last; it is not how selection happens. Where an instruction outside the guide contradicts it (a stale `CLAUDE.md` line, a retired command still recommended), propose the concrete fix to that file — leaving two live contradictory instructions is a defect. 6. **Coverage check and close.** Go through the memlog: every accepted candidate must trace to a guide line, a scoped guide, or a rejection with a reason — and, in the other direction, every line in the guide must trace to a memlog candidate. A line with no candidate slipped in at composition time without evidence: backfill it with real evidence or delete it. Check every repo-relative path the guide names against the filesystem; fix dead links before closing. Confirm the guide fits the contract's budget. Tell the user what was written, what was rejected and why, and — whenever `AGENTS.md` carries the guide — that a harness which doesn't auto-load `AGENTS.md` needs its own file to pull it in (e.g. a `CLAUDE.md` containing `@AGENTS.md`). -**Refresh:** same steps against the existing guide and memlog. Never re-ask what a prior run settled; re-verify the commands and paths the guide states; update or remove lines whose evidence is gone. The guide grows only when new evidence justifies it. +**Refresh:** same steps against the existing guide and memlog. Never re-ask what a prior run settled; re-verify the commands and paths the guide states; run `git log --diff-filter=DR --name-only` since the last run and check every deleted or renamed path against every guide line; update or remove lines whose evidence is gone. The guide grows only when new evidence justifies it. -**Greenfield:** same process, based on a spec or planning document (or interview alone). Commands that don't exist yet are written from the decided stack and marked for verification on the first refresh after code exists. A genuinely contested design decision — real tradeoffs, multiple viable shapes — deserves the `bmad-architecture` skill rather than a call made here. +**Greenfield:** same process, based on a spec or planning document (or interview alone). Commands that don't exist yet are written as explicit TODO placeholders from the decided stack — never a guessed invocation stated as fact — and verified on the first refresh after code exists. A genuinely contested design decision — real tradeoffs, multiple viable shapes — deserves the `bmad-architecture` skill rather than a call made here. ## Record diff --git a/src/bmm-skills/plan/bmad-project-context/references/evidence.md b/src/bmm-skills/plan/bmad-project-context/references/evidence.md index 211b7a294..b29961870 100644 --- a/src/bmm-skills/plan/bmad-project-context/references/evidence.md +++ b/src/bmm-skills/plan/bmad-project-context/references/evidence.md @@ -9,7 +9,7 @@ Sources 1–5 are scanner work; source 6 is the interview. Later sources hold wh 1. **Existing recorded instructions and lessons** — root and nested `AGENTS.md`, `CLAUDE.md`, editor rule files, and lessons written anywhere nearby (notes files, warnings in READMEs). What agents are told today: the baseline, plus conflicts and stale claims to fix. Recorded lessons are standing maintainer testimony — kept by default, challenged only with evidence that a referent is gone or wrong. 2. **Executable configuration and CI** — manifests, lockfiles, workflow files, hooks, Makefiles, linter configs. Most of Commands, Verification, and Policy comes from here, verified by execution. 3. **Tracked source** — boundaries (vendored, generated, frozen), conventions that differ from defaults, entry points. Scanned to answer the section plan's questions, never for novelty: an interesting fact no agent needs is noise, and a trap-looking fact is at most an interview question, never a pitfall line. -4. **Git history** — targeted, never wholesale: when the current state contains a surprising constraint, find the change that introduced it and any reverted attempts to remove it, then check the reason still holds today. Commit messages are past intent, not current truth. +4. **Git history** — targeted, never wholesale: when the current state contains a surprising constraint, find the change that introduced it and any reverted attempts to remove it, then check the reason still holds today. Also the source for commit-message and branch-naming conventions, read off recent history. Commit messages are past intent, not current truth. 5. **Agent session logs and review corrections** — when available or pointed at: the only source of *observed* agent mistakes. Extract structure, never transcripts: task, mistake, correction, consequence, occurrence count, source sessions. One occurrence is a candidate; recurrence makes a pitfall line. Ignore one-off noise (tool outages, typos); route mechanically preventable mistakes to a proposed hook, lint, or CI check instead of prose. 6. **The human** — org requirements, domain concepts, frozen areas, intent, priorities, and mistakes they've watched agents make. No scan substitutes. diff --git a/src/bmm-skills/plan/bmad-project-context/references/guide-contract.md b/src/bmm-skills/plan/bmad-project-context/references/guide-contract.md index bf7c5a43a..11c29e5e9 100644 --- a/src/bmm-skills/plan/bmad-project-context/references/guide-contract.md +++ b/src/bmm-skills/plan/bmad-project-context/references/guide-contract.md @@ -40,7 +40,7 @@ Each section has its own admission rule. There is no global "non-derivable" test ## Shape and style -Terse imperative lines under plain headings — no prose paragraphs beyond Orientation, no introduction, no summary. Every line states what to do or what not to do; a bare fact may appear only as the justification clause of such a line ("Exclude `vendor/` from searches — it is 60% of the tracked files", never "`vendor/` is 60% of the tracked files"). Use the contract's section headings so the guide's shape is recognizable across runs; material that seems to need a new section folds into the nearest one. State present truth only; git holds history. Every named decision, doc, file, or system includes a repo-relative path or URL that exists. Target shape: +Terse imperative lines under plain headings — no prose paragraphs beyond Orientation, no introduction, no summary. Every line states what to do or what not to do; a bare fact may appear only as the justification clause of such a line ("Exclude `vendor/` from searches — it is 60% of the tracked files", never "`vendor/` is 60% of the tracked files"). Use the contract's section headings so the guide's shape is recognizable across runs; material that seems to need a new section folds into the nearest one. A prohibition names the permitted alternative — "never force-push; use a new branch" — because a bare "never" leaves the agent stuck at the moment it matters. At most two emphasis markers (IMPORTANT, YOU MUST, bold caps) in the whole guide; past that, emphasis stops working. State present truth only; git holds history. Every named decision, doc, file, or system includes a repo-relative path or URL that exists. Target shape: `AGENTS.md`: