From 6f9de57b0ce5b5f700465d69af1cd6b13beeec64 Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Mon, 8 Jun 2026 18:56:30 +0300 Subject: [PATCH] =?UTF-8?q?refactor(brainstorm-with-docs):=20=D0=BF=D0=BE?= =?UTF-8?q?=D0=BD=D0=B8=D0=BC=D0=B0=D0=BD=D0=B8=D0=B5=20=D0=B2=D0=B5=D0=B4?= =?UTF-8?q?=D1=91=D1=82,=20=D0=B0=D1=80=D1=82=D0=B5=D1=84=D0=B0=D0=BA?= =?UTF-8?q?=D1=82=20=E2=80=94=20=D0=B7=D0=B0=D0=BF=D0=B8=D1=81=D1=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - гравитация скилла тянула к «выдать артефакт»; управляющие документы раздувались деталями реализации (диагностировано на живом тесте — 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) --- .../skills/brainstorm-with-docs/README.md | 10 +++--- .../skills/brainstorm-with-docs/SKILL.md | 36 ++++++++++++++----- .../brainstorm-with-docs/artifacts/adr.md | 14 +++++--- .../brainstorm-with-docs/artifacts/spec.md | 10 +++--- 4 files changed, 48 insertions(+), 22 deletions(-) diff --git a/agents/.agents/skills/brainstorm-with-docs/README.md b/agents/.agents/skills/brainstorm-with-docs/README.md index a16dfd3..828f11b 100644 --- a/agents/.agents/skills/brainstorm-with-docs/README.md +++ b/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 -artifact: a spec, ADR, runbook, research note, or `CONTEXT.md` glossary update. +or documentation problem and drives it to shared understanding and a recommended +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 - artifact: glossary entry, spec, ADR, runbook, research note, or PRD. +- **durable output** — the understanding is the deliverable; it's recorded in the + 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 diff --git a/agents/.agents/skills/brainstorm-with-docs/SKILL.md b/agents/.agents/skills/brainstorm-with-docs/SKILL.md index f8199a9..6175b83 100644 --- a/agents/.agents/skills/brainstorm-with-docs/SKILL.md +++ b/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 -updating the agreed documentation artifact, STOP. +Approval of a design direction is NOT approval to implement. The deliverable of +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 ``.) 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 -thinking. +matching `artifacts/*.md` file. Choose the minimum-sufficient form — the smallest +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. -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: diff --git a/agents/.agents/skills/brainstorm-with-docs/artifacts/adr.md b/agents/.agents/skills/brainstorm-with-docs/artifacts/adr.md index bb72a71..3f32abe 100644 --- a/agents/.agents/skills/brainstorm-with-docs/artifacts/adr.md +++ b/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 -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. +**Scope test (ADR vs spec).** Both an ADR and a spec are durable records, so the +split isn't lifetime — it's scope. A spec captures the shape of *one piece of +work* (what we're building and why); an ADR captures a single decision that is +*cross-cutting* — it matters beyond that one piece of work, and a future reader +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 diff --git a/agents/.agents/skills/brainstorm-with-docs/artifacts/spec.md b/agents/.agents/skills/brainstorm-with-docs/artifacts/spec.md index 9c85c4a..89b2792 100644 --- a/agents/.agents/skills/brainstorm-with-docs/artifacts/spec.md +++ b/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 -add nothing for this particular problem — an empty section is noise. +Use the minimum-sufficient version: the smallest form that fully preserves the +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 -this spec is obsolete (see the lifetime test in `artifacts/adr.md`). +durable, surprising, the result of a real trade-off, and matters beyond the scope +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`.