refactor(brainstorm-with-docs): понимание ведёт, артефакт — запись

- Зачем:
  - гравитация скилла тянула к «выдать артефакт»; управляющие документы
    раздувались деталями реализации (диагностировано на живом тесте — ADR
    с инлайном SQL).
- Что:
  - gate/stop: «готово» = общее понимание + рекомендованное направление,
    записанное минимально-достаточно, а не «артефакт произведён»; определение
    в одном месте (stop_condition), gate на него ссылается.
  - core_rules: минимально-достаточный артефакт + барьер высоты (без инлайна
    исполняемых артефактов) + single source of truth; приоритет над
    конвенциями репозитория.
  - шаг 2: артефакт(ы) выбираются ПОСЛЕ понимания, набором по жанрам.
  - adr.md/spec.md: Lifetime test → Scope test (ADR↔spec по охвату, не сроку);
    detailed plan — transient и вне scope скилла.
  - description + README: формулировки-цели ведут пониманием, не артефактом.
- Проверка:
  - grep: старый framing (lifetime/transient) убран; cross-ref Scope test
    сходится; определение «готово» не дублируется; витрина не artifact-first.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

agents/.agents/skills/brainstorm-with-docs/README.md

@@ -3,8 +3,9 @@
 A manually-invoked skill for **brainstorming, design alignment, and durable
 documentation** — grounded in a project's existing docs and vocabulary. It takes
 an unclear engineering, DevOps, architecture, migration, integration, research,
-or documentation problem and turns it into the *smallest useful* durable
+or documentation problem and drives it to shared understanding and a recommended
-artifact: a spec, ADR, runbook, research note, or `CONTEXT.md` glossary update.
+direction — recorded in the *smallest useful* durable artifact: a spec, ADR,
+runbook, research note, or `CONTEXT.md` glossary update.
 
 It is deliberately **not** an implementation skill. It reads project files and
 proposes documentation, but stops before code, config, or infrastructure changes
@@ -22,8 +23,9 @@ It combines four things that are usually separate:
 - **option exploration** — comparing 2-3 viable approaches within the user's
   framing, plus at least one framing-challenger so the agent does not only
   optimise inside the first shape of the problem;
-- **durable output** — turning the useful thinking into the smallest appropriate
+- **durable output** — the understanding is the deliverable; it's recorded in the
-  artifact: glossary entry, spec, ADR, runbook, research note, or PRD.
+  smallest appropriate artifact: glossary entry, spec, ADR, runbook, research
+  note, or PRD.
 
 The closest day-to-day comparison is `grill-me`: use `grill-me` when you mainly
 want the agent to pull understanding out of you and align on a plan in the

agents/.agents/skills/brainstorm-with-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorm-with-docs
-description: Structured brainstorming and design alignment for unclear technical problems, grounded in the project's existing docs and vocabulary — questioning assumptions, sharpening terminology, comparing options, and recommending a direction. Use when exploring an ambiguous engineering, DevOps, architecture, migration, integration, research, or documentation problem and turning it into a durable artifact such as a spec, ADR, runbook, research note, or CONTEXT.md glossary update. Not for implementation, trivial fixes, or executing an already-approved plan.
+description: Structured brainstorming and design alignment for unclear technical problems, grounded in the project's existing docs and vocabulary — questioning assumptions, sharpening terminology, comparing options, and reaching shared understanding and a recommended direction. Use when exploring an ambiguous engineering, DevOps, architecture, migration, integration, research, or documentation problem; the understanding is the deliverable, recorded in the smallest durable artifact (spec, ADR, runbook, research note, or CONTEXT.md glossary update). Not for implementation, trivial fixes, or executing an already-approved plan.
 disable-model-invocation: true
 argument-hint: "[problem-or-topic]"
 allowed-tools: Read Grep Glob Write Edit WebSearch WebFetch Bash(git log:*) Bash(git diff:*) Bash(git status:*) Bash(git show:*)
@@ -19,8 +19,10 @@ Do NOT write code, change configuration or infrastructure, run state-changing
 commands, refactor, run migrations, deploy, or invoke any implementation skill
 until the user has approved a design AND explicitly asked to implement.
 
-Approval of a design direction is NOT approval to implement. After producing or
+Approval of a design direction is NOT approval to implement. The deliverable of
-updating the agreed documentation artifact, STOP.
+this skill is shared understanding and a recommended direction; the document is
+only the smallest record that preserves it, never the goal in itself. (When you
+are done, and how to stop, is in `<stop_condition>`.)
 
 The skill may freely investigate — read project files, run read-only inspection
 commands, and look up external documentation — and may create or update
@@ -76,7 +78,17 @@ If invoked with arguments, treat `$ARGUMENTS` as the initial problem statement.
 * Be direct. Give a real recommendation; don't hide behind "it depends" when the
   context supports a call.
 * Explicitly state what should NOT be done now.
-* Use the smallest artifact that preserves the useful thinking.
+* Minimum-sufficient artifact: the smallest form that *fully* preserves the
+  understanding — and no smaller. Sized to the understanding, not "as small as
+  possible": a large understanding earns a fuller document, a small one a paragraph.
+* Keep documents at decision altitude: record the decision and the understanding
+  in prose. Do NOT inline executable artifacts (code, config, DDL, schemas) — name
+  the decision and point to the artifact that holds it. Inlining executable detail
+  is implementation, even when it looks like "stating the decision precisely".
+* Each fact lives in one artifact — cross-reference, never duplicate. Several
+  artifacts from one understanding is fine; the same content in several is not.
+  These altitude and size rules outrank a heavier local doc style: match the
+  repo's section structure, but don't inflate or duplicate to fit it.
 * Keep `CONTEXT.md` strictly a glossary; create ADRs only sparingly.
 * Do not produce a detailed implementation plan unless the user asks for one.
 
@@ -104,9 +116,14 @@ listing files, inspecting data, querying a dev datastore. That's expected: run
 them (they may prompt for approval), since grounding options in real data is this
 skill's main strength. Never run state-changing commands (see the gate).
 
-## 2. Classify the work and pick the likely artifact
+## 2. Note candidate artifacts (don't commit yet)
 
-Decide what kind of work this is, then which artifact is likely to fit:
+Understanding leads; the artifact is its crystallization — so don't pick an
+artifact to aim at here. Just keep in mind which kinds the understanding might
+crystallize into, and commit only at step 6, once you understand the problem. One
+understanding may map to several artifacts (e.g. an ADR for a cross-cutting
+decision *and* a spec for the shape of the work), each holding a different facet.
+The kinds, for reference:
 
 * answer still unknown → [research note](artifacts/research-note.md)
 * direction chosen, not yet built → [spec / solution design](artifacts/spec.md)
@@ -184,8 +201,8 @@ vocabulary.
 ## 7. Write the artifact
 
 Once the user agrees, create or update the artifact, following the format in the
-matching `artifacts/*.md` file. Choose the smallest form that preserves the
+matching `artifacts/*.md` file. Choose the minimum-sufficient form — the smallest
-thinking.
+that fully preserves the understanding, and no smaller.
 
 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
@@ -231,7 +248,8 @@ interview.
 
 <stop_condition>
 
-After the artifact is produced, STOP. Do not start coding, change
+You are done once the understanding is shared and minimally recorded — not when
+an artifact has been produced. Then STOP. Do not start coding, change
 infrastructure, alter configuration, or run state-changing commands unless the
 user explicitly asks. Offer a small set of next actions, such as:
 

agents/.agents/skills/brainstorm-with-docs/artifacts/adr.md

@@ -18,11 +18,15 @@ 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
+**Scope test (ADR vs spec).** Both an ADR and a spec are durable records, so the
-built now and goes stale once the work is done. An ADR is durable — it outlives
+split isn't lifetime — it's scope. A spec captures the shape of *one piece of
-the spec. So record a decision in an ADR only when it stays relevant *after* the
+work* (what we're building and why); an ADR captures a single decision that is
-spec that introduced it is obsolete. Decisions local to the current work belong
+*cross-cutting* — it matters beyond that one piece of work, and a future reader
-in the spec's "Decisions and rejected alternatives" section, not here.
+elsewhere will need its rationale. So record a decision in an ADR only when it
+applies beyond the scope of the spec that introduced it. Decisions local to the
+current work belong in the spec's "Decisions and rejected alternatives" section,
+not here. (The transient, stale-able document is the detailed implementation
+plan — a separate artifact, not produced by this skill.)
 
 ## Template
 

agents/.agents/skills/brainstorm-with-docs/artifacts/spec.md

@@ -3,8 +3,9 @@
 Use for engineering, architecture, DevOps, integration, migration, or any
 non-product feature work where a direction has been chosen but not yet built.
 
-Use the smallest version that preserves the useful thinking. Drop sections that
+Use the minimum-sufficient version: the smallest form that fully preserves the
-add nothing for this particular problem — an empty section is noise.
+understanding, and no smaller. Drop sections that add nothing for this particular
+problem — an empty section is noise.
 
 ## Template
 
@@ -57,8 +58,9 @@ in the second.
 
 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
+durable, surprising, the result of a real trade-off, and matters beyond the scope
-this spec is obsolete (see the lifetime test in `artifacts/adr.md`).
+of this work — cross-cutting, relevant to readers elsewhere (see the scope 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`.