docs(skills): brainstorm-with-docs — шов self_review развязан двумя ярусами

Самопроверка уехала до записи и работает по плану артефакта (уровень
решений; может вернуть в интервью, пока файла нет) — сверено с апстримом
Мэтта: валидация до записи, запись линейна. После записи — дешёвое
перечитывание готового файла глазами читателя, правки по месту, решения
не переоткрываются. Критерий конца интервью оставлен мягким (решение
владельца, в Rejected), версионный хвост в шаблоне context.md вычищен.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

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
+The cold review caught that `<self_review>` ran "before presenting" but *after*
-  file is written; unclear what happens to the written artifact if review sends
+the file was written — order unstated, and a review verdict of "continue the
-  the run back to the interview. Candidate fixes: review the draft before
+interview" left a half-baked artifact on disk with no instructions. Resolution,
-  writing, or state honestly "write → review → patch; if a gap opens, back to
+shaped by three inputs:
-  the interview, then update the artifact".
+
-- **Interview stop criterion.** "Clear enough to synthesize" is vague; candidate
+- **Upstream comparison** (owner's call to check Matt Pocock's current skills):
-  hardening: problem, constraints, and success criteria named + no open forks
+  Matt has no post-write review at all — `domain-modeling` writes glossary/ADRs
-  left.
+  inline as terms resolve ("don't batch"; our gate exception for inline capture
-- **Version notes in templates.** `artifacts/context.md` carries "(Multi-context
+  independently converged on this), and `to-spec` synthesizes from the
-  handling is deliberately light in v1.)" — development history in agent-facing
+  conversation with its only checkpoint *before* the write. Pattern: validate
-  text; belongs here, not there.
+  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: `<self_review>` 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.

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.
+Run `<self_review>` on the artifact plan — the outline and its key content
-Confirmation can be lightweight, e.g.:
+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
-`<core_rules>`.
+`<core_rules>`. 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 `<self_review>` and `<stop_condition>`.
+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 `<self_review>` at step 6).
+
+Then go to `<stop_condition>`.
 
 </how_to_do_it>
 
@@ -259,14 +271,16 @@ runbook. If it's a validation rule for this work → the spec.
 
 <self_review>
 
-This is a review of the document itself — distinct from a spec's `## Validation`
+A review of the artifact *plan* — the outline and its key content decisions —
-section, which lists acceptance criteria for the implementation.
+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
+Check the plan for: unclear terms, missing constraints, hidden assumptions,
-constraints, hidden assumptions, contradictions with existing docs, unnecessary
+contradictions with existing docs, unnecessary scope expansion, premature
-scope expansion, premature implementation detail, missing validation criteria,
+implementation detail, missing validation criteria, decisions that should (or
-decisions that should (or should not) be ADRs, operational steps that should be a
+should not) be ADRs, operational steps that should be a runbook, and context
-runbook, and context that does (or does not) belong in `CONTEXT.md`.
+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.

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.