From f24b34212382f33e25c99a2fdd634dbc799a422b Mon Sep 17 00:00:00 2001
From: Dmitry Dementev <me@dementev.space>
Date: Tue, 2 Jun 2026 23:43:09 +0300
Subject: [PATCH] =?UTF-8?q?docs(brainstorm-with-docs):=20=D1=83=D1=82?=
 =?UTF-8?q?=D0=BE=D1=87=D0=BD=D0=B5=D0=BD=D1=8B=20=D0=B3=D1=80=D0=B0=D0=BD?=
 =?UTF-8?q?=D0=B8=D1=86=D1=8B=20=D0=B0=D1=80=D1=82=D0=B5=D1=84=D0=B0=D0=BA?=
 =?UTF-8?q?=D1=82=D0=BE=D0=B2=20=D0=BF=D0=BE=20=D0=B2=D0=BD=D0=B5=D1=88?=
 =?UTF-8?q?=D0=BD=D0=B5=D0=BC=D1=83=20=D1=80=D0=B5=D0=B2=D1=8C=D1=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Зачем:
  - внешнее ревью выявило риск двойной записи решений (spec/ADR) и
    терминологическую путаницу; правки документные, поведение не меняют.
- Что:
  - adr.md и spec.md: добавлен lifetime-критерий ADR vs spec (ADR — для
    решений, переживающих спеку; локальные остаются в спеке).
  - spec.md: разведены Options considered (до выбора) и Decisions (после).
  - SKILL.md: блок <validation> переименован в <self_review>, чтобы не
    путать с секцией ## Validation в spec.md.
  - README.md: честнее описано авто-срабатывание на Codex.
  - SKILL.md: у SEAM зафиксирован TODO(F1) про строку дивергенции
    (отложена ради чистого baseline на обкатке).
- Проверка:
  - python3 yaml-парс frontmatter; нет висячих ссылок на <validation>.
---
 .../skills/brainstorm-with-docs/README.md     |  5 ++++-
 .../skills/brainstorm-with-docs/SKILL.md      | 22 ++++++++++++++-----
 .../brainstorm-with-docs/artifacts/adr.md     |  6 +++++
 .../brainstorm-with-docs/artifacts/spec.md    | 14 +++++++++---
 4 files changed, 37 insertions(+), 10 deletions(-)

diff --git a/agents/.agents/skills/brainstorm-with-docs/README.md b/agents/.agents/skills/brainstorm-with-docs/README.md
index ef25d08..04820ab 100644
--- a/agents/.agents/skills/brainstorm-with-docs/README.md
+++ b/agents/.agents/skills/brainstorm-with-docs/README.md
@@ -33,7 +33,10 @@ Invoke manually:
 On **Claude Code** the skill is manual-only (`disable-model-invocation: true`) —
 it never auto-triggers; you always call it. On **Codex** that field is ignored
 (Codex reads only `name` + `description`), so it may auto-trigger on matching
-design tasks; the negative triggers in the description keep that disciplined.
+design tasks. The negative triggers in the description discourage that, but the
+description's positive surface is broad (architecture / DevOps / research), so
+expect it to fire more eagerly on Codex than on Claude. If that gets noisy,
+narrow the description.
 
 ## Layout
 
diff --git a/agents/.agents/skills/brainstorm-with-docs/SKILL.md b/agents/.agents/skills/brainstorm-with-docs/SKILL.md
index 88752eb..5f0a928 100644
--- a/agents/.agents/skills/brainstorm-with-docs/SKILL.md
+++ b/agents/.agents/skills/brainstorm-with-docs/SKILL.md
@@ -143,9 +143,16 @@ in [artifacts/context.md](artifacts/context.md) — don't batch them.
 
 ## 5. Synthesize options
 
-<!-- SEAM: v2 will prepend a divergence phase (idea-generation toolkit +
-     "at least one option the user didn't already imply") before this
-     convergence step. Keep this step self-contained so it can be split. -->
+<!-- SEAM / TODO(v2): prepend a divergence phase before this convergence step.
+     Full version = idea-generation toolkit (axis of variation, archetype
+     stances, inversion, steal-from-adjacent-domain, cost-shifting, pre-mortem,
+     constraint relaxation, null option).
+     TODO(F1): cheap pre-step — add one <core_rule>: "among the options, at least
+     one must be something the user did not already imply." Deliberately deferred
+     now to keep the v1 live-test baseline clean (we want to see how badly pure
+     convergence collapses into variations of one idea). Reconsider landing this
+     single line right after the first live test, before the full toolkit.
+     Keep this step self-contained so it can be split. -->
 
 Present 2-3 viable approaches. For each: short description, when it fits,
 benefits, trade-offs, risks, operational implications, documentation impact, and
@@ -178,7 +185,7 @@ 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 `<validation>` and `<stop_condition>`.
+Then go to `<self_review>` and `<stop_condition>`.
 
 </how_to_do_it>
 
@@ -198,7 +205,10 @@ runbook. If it's a validation rule for this work → the spec.
 
 </shared_project_language>
 
-<validation>
+<self_review>
+
+This is a review of the document itself — 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
@@ -209,7 +219,7 @@ 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.
 
-</validation>
+</self_review>
 
 <stop_condition>
 
diff --git a/agents/.agents/skills/brainstorm-with-docs/artifacts/adr.md b/agents/.agents/skills/brainstorm-with-docs/artifacts/adr.md
index 239b073..bb72a71 100644
--- a/agents/.agents/skills/brainstorm-with-docs/artifacts/adr.md
+++ b/agents/.agents/skills/brainstorm-with-docs/artifacts/adr.md
@@ -18,6 +18,12 @@ If any of the three is missing, skip it. Easy to reverse → you'll just reverse
 it. Not surprising → nobody will wonder. No real alternative → nothing to record
 beyond "we did the obvious thing". Do not create an ADR for every small choice.
 
+**Lifetime test (ADR vs spec).** A spec is transient — it describes what's being
+built now and goes stale once the work is done. An ADR is durable — it outlives
+the spec. So record a decision in an ADR only when it stays relevant *after* the
+spec that introduced it is obsolete. Decisions local to the current work belong
+in the spec's "Decisions and rejected alternatives" section, not here.
+
 ## Template
 
 ```markdown
diff --git a/agents/.agents/skills/brainstorm-with-docs/artifacts/spec.md b/agents/.agents/skills/brainstorm-with-docs/artifacts/spec.md
index 0febebd..9c85c4a 100644
--- a/agents/.agents/skills/brainstorm-with-docs/artifacts/spec.md
+++ b/agents/.agents/skills/brainstorm-with-docs/artifacts/spec.md
@@ -40,6 +40,13 @@ add nothing for this particular problem — an empty section is noise.
 
 ## Notes on key sections
 
+**Options considered vs Decisions.** Keep these two sections doing different jobs
+so the rejected options aren't written twice. *Options considered* is the
+landscape *before* the choice — the candidates and their trade-offs as they
+stood. *Decisions and rejected alternatives* is the outcome *after* the choice —
+what was picked and why each alternative was rejected. Frame in the first, judge
+in the second.
+
 **Decisions and rejected alternatives** is the highest-value section. Capture:
 
 - accepted decisions and the reason behind each
@@ -48,9 +55,10 @@ add nothing for this particular problem — an empty section is noise.
 - sequencing decisions
 - assumptions future agents must not silently re-derive
 
-Do not turn this section into an ADR dump. Promote a decision to its own ADR
-(`artifacts/adr.md`) only when it is durable, surprising, and the result of a
-real trade-off.
+Do not turn this section into an ADR dump. Keep decisions that are local to this
+work here; promote a decision to its own ADR (`artifacts/adr.md`) only when it is
+durable, surprising, the result of a real trade-off, and will still matter after
+this spec is obsolete (see the lifetime test in `artifacts/adr.md`).
 
 **Validation** describes how we will know the implementation is correct — tests,
 checks, acceptance criteria. It belongs here, not in `CONTEXT.md`.