diff --git a/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md b/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md index 7eec5e3..b7275b0 100644 --- a/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md +++ b/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md @@ -133,19 +133,32 @@ the skill cold. Applied same day: README Roadmap section reduced to a pointer at this file (it had become a second source of truth). -## Pending decisions (2026-08-01 cold review, deferred by owner) +## Landed (2026-08-01, step 7 / self_review seam resolved) -- **Step 7 / self_review seam.** Review runs "before presenting" but after the - file is written; unclear what happens to the written artifact if review sends - the run back to the interview. Candidate fixes: review the draft before - writing, or state honestly "write → review → patch; if a gap opens, back to - the interview, then update the artifact". -- **Interview stop criterion.** "Clear enough to synthesize" is vague; candidate - hardening: problem, constraints, and success criteria named + no open forks - left. -- **Version notes in templates.** `artifacts/context.md` carries "(Multi-context - handling is deliberately light in v1.)" — development history in agent-facing - text; belongs here, not there. +The cold review caught that `` ran "before presenting" but *after* +the file was written — order unstated, and a review verdict of "continue the +interview" left a half-baked artifact on disk with no instructions. Resolution, +shaped by three inputs: + +- **Upstream comparison** (owner's call to check Matt Pocock's current skills): + Matt has no post-write review at all — `domain-modeling` writes glossary/ADRs + inline as terms resolve ("don't batch"; our gate exception for inline capture + independently converged on this), and `to-spec` synthesizes from the + conversation with its only checkpoint *before* the write. Pattern: validate + before writing; the write itself is linear. +- **Owner's size nuance:** artifacts can be large — a full draft pass through + the chat before writing would push the whole text through context twice. So + the pre-write review runs on the artifact *plan* (outline + key content + decisions); the checklist is decision-altitude anyway, only "unclear terms" + is wording-level. +- **Owner's experience:** a cheap re-read of the finished document by its own + author regularly finds real defects. Kept, as a second tier. + +Landed shape — two tiers: `` runs at step 6 on the plan (can send +the run back to the interview; no file exists yet), step 7 writes the file once +directly, then re-reads it end-to-end as a reader and fixes text-level defects +in place (does not reopen decisions). Unlike upstream, the review itself is +kept — `to-spec` has none; ours has content worth keeping. ## v2 — remaining @@ -163,3 +176,10 @@ Kept from before: - **F6 — "space-separated `allowed-tools` won't parse."** False. Claude Code docs accept space- or comma-separated or YAML list; and `allowed-tools` is pre-approval, not a restriction. No change needed. +- **Hard interview-stop checklist** (cold-review finding, 2026-08-01). Proposal: + replace "clear enough to synthesize" with a checkable triple (problem, + constraints, success criteria named + no open forks). Owner's call: keep it + soft — a hard checklist pushes the interview toward box-ticking. Consistent + with the R2 verdict from the first test (relentlessness left SOFT). The + version-note tail in `artifacts/context.md` from the same review was simply + cleaned. diff --git a/agents/.agents/skills/brainstorm-with-docs/SKILL.md b/agents/.agents/skills/brainstorm-with-docs/SKILL.md index 877adfb..cdf6ea5 100644 --- a/agents/.agents/skills/brainstorm-with-docs/SKILL.md +++ b/agents/.agents/skills/brainstorm-with-docs/SKILL.md @@ -214,8 +214,13 @@ the ADR's options considered). ## 6. Confirm direction -Before writing or changing durable project documents, confirm the direction. -Confirmation can be lightweight, e.g.: +Run `` on the artifact plan — the outline and its key content +decisions — before proposing it: the checklist works at decision altitude, no +full draft needed. If it opens a gap, return to the interview while no file +exists yet. + +Then confirm the direction before writing or changing durable project +documents. Confirmation can be lightweight, e.g.: > "I recommend option B. I'd document it as a solution design, add one > lightweight ADR for the storage-layout decision, and add two terms to @@ -229,7 +234,8 @@ vocabulary. Once the user agrees, create or update the artifact, following the format in the matching `artifacts/*.md` file, sized by the minimum-sufficient rule from -``. +``. Write the file once, directly — the plan passed review at step +6, so no draft pass through the chat. Where it goes: follow the repo's existing documentation layout if there is one. Otherwise use the conventional homes — `CONTEXT.md` at the repo root, ADRs in @@ -237,7 +243,13 @@ Otherwise use the conventional homes — `CONTEXT.md` at the repo root, ADRs in `docs/runbooks/`). If the location isn't obvious, propose a path and confirm it as part of step 6 rather than guessing. Create directories lazily. -Then go to `` and ``. +After writing, re-read the written file end-to-end as its reader, not its +author, and fix what you find in place — wording, structure drift, sections +that disagree with each other, template mismatches. This pass is cheap and +regularly catches real defects; it polishes text, it does not reopen decisions +(those passed `` at step 6). + +Then go to ``. @@ -259,14 +271,16 @@ runbook. If it's a validation rule for this work → the spec. -This is a review of the document itself — distinct from a spec's `## Validation` -section, which lists acceptance criteria for the implementation. +A review of the artifact *plan* — the outline and its key content decisions — +run at step 6, before any file is written, so a gap sends the run back to the +interview while nothing sits half-baked on disk. Distinct from a spec's +`## Validation` section, which lists acceptance criteria for the implementation. -Before presenting the final artifact, review it for: unclear terms, missing -constraints, hidden assumptions, contradictions with existing docs, unnecessary -scope expansion, premature implementation detail, missing validation criteria, -decisions that should (or should not) be ADRs, operational steps that should be a -runbook, and context that does (or does not) belong in `CONTEXT.md`. +Check the plan for: unclear terms, missing constraints, hidden assumptions, +contradictions with existing docs, unnecessary scope expansion, premature +implementation detail, missing validation criteria, decisions that should (or +should not) be ADRs, operational steps that should be a runbook, and context +that does (or does not) belong in `CONTEXT.md`. If it's too large, propose splitting it. If it's too vague, continue the interview. diff --git a/agents/.agents/skills/brainstorm-with-docs/artifacts/context.md b/agents/.agents/skills/brainstorm-with-docs/artifacts/context.md index c1c099a..808df20 100644 --- a/agents/.agents/skills/brainstorm-with-docs/artifacts/context.md +++ b/agents/.agents/skills/brainstorm-with-docs/artifacts/context.md @@ -6,7 +6,7 @@ devoid of implementation details, decisions, plans, or work logs. A single `CONTEXT.md` lives at the repo root. If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts — read it to find which `CONTEXT.md` the -current topic belongs to. (Multi-context handling is deliberately light in v1.) +current topic belongs to. Create the file lazily — only when the first term is actually worth recording.