From d10ad6981c9afb97d3a6b4a0a1b123efcf147663 Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Sat, 1 Aug 2026 18:40:38 +0300 Subject: [PATCH] =?UTF-8?q?docs(skills):=20brainstorm-with-docs=20?= =?UTF-8?q?=E2=80=94=20=D0=BF=D1=80=D0=B0=D0=B2=D0=BA=D0=B8=20=D0=BF=D0=BE?= =?UTF-8?q?=20=D1=85=D0=BE=D0=BB=D0=BE=D0=B4=D0=BD=D0=BE=D0=BC=D1=83=20?= =?UTF-8?q?=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 README перестал объявлять скилл ручным: model-invocation — намеренное текущее состояние (триггер — форма задачи, не область). Жёсткий гейт получил исключение для глоссария (спорил с шагом 4) и стал единственным владельцем запрета на реализацию; дубли правил схлопнуты к владельцам. Отложенные находки (шов self_review, критерий конца интервью, версионные пометки в шаблонах) — в Pending decisions ROADMAP. Co-Authored-By: Claude Opus 5 --- .../skills/brainstorm-with-docs/README.md | 43 ++++++++----------- .../skills/brainstorm-with-docs/ROADMAP.md | 41 ++++++++++++++++++ .../skills/brainstorm-with-docs/SKILL.md | 25 ++++++----- 3 files changed, 70 insertions(+), 39 deletions(-) diff --git a/agents/.agents/skills/brainstorm-with-docs/README.md b/agents/.agents/skills/brainstorm-with-docs/README.md index f839d1a..0d3a2d4 100644 --- a/agents/.agents/skills/brainstorm-with-docs/README.md +++ b/agents/.agents/skills/brainstorm-with-docs/README.md @@ -1,11 +1,11 @@ # brainstorm-with-docs -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 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. +A skill for **brainstorming, design alignment, and durable documentation** — +grounded in a project's existing docs and vocabulary. It takes an ambiguous +problem — whatever the domain — or a decision fork (развилка) 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 @@ -36,19 +36,18 @@ to follow that methodology wholesale. ## Usage -Invoke manually: +Model-invoked: the agent reaches for the skill on its own when it sees an +ambiguous problem or a decision fork (развилка) — the trigger is the shape of +the task, not its domain. (It started life manual-only; live use showed the +whole value is in the agent reaching it unprompted.) You can also invoke it by +name: ``` /brainstorm-with-docs ``` -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 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. +A repo can route to it explicitly — e.g. an `AGENTS.md` line sending decision +forks here. ## Layout @@ -56,6 +55,7 @@ narrow the description. brainstorm-with-docs/ ├── SKILL.md # the skill: process, rules, grill mechanics ├── README.md # this file +├── ROADMAP.md # development memory: status, backlog, evidence └── artifacts/ # output templates — read only the one you need ├── spec.md # solution design / engineering spec ├── research-note.md # exploratory, answer not yet known @@ -70,18 +70,9 @@ Templates are split per type so the agent loads only what's relevant ## Roadmap -- **v1:** working hybrid — context inspection, glossary/ADR discipline, - active grilling, option comparison with an additive framing-challenger, durable - artifacts, stop-before-implementation. -- **v2 divergence (current):** step 5 is a diverge-then-converge split — frame - restatement, mandatory frame-challenger and null option, fan width tiered by - decision weight, an idea-generation toolkit with WHEN-triggers, a diversity - self-check, and fork-in-place grilling during the interview (step 4). -- **Remaining:** a "design for isolation" lens and fuller multi-context support. - -See [ROADMAP.md](ROADMAP.md) for the full backlog, pending decisions, and what -has been considered and rejected. `ROADMAP.md` is development memory and can be -removed once the skill stabilises. +Status, backlog, pending decisions, live-test evidence, and rejected ideas live +in [ROADMAP.md](ROADMAP.md) — the single source of truth. It is development +memory and can be removed once the skill stabilises. ## Attribution diff --git a/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md b/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md index 4cc2686..7eec5e3 100644 --- a/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md +++ b/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md @@ -106,6 +106,47 @@ skill router matches it; (b) a repo-side routing line in the project's future repos. The third-party grilling skill stays unforked; this skill owns the fan practice. +## Landed (2026-08-01, from cold review) + +A fresh-session reviewer (no shared context, writing-great-skills lens) read +the skill cold. Applied same day: + +- **README "manual-only" claim was stale** — the worst kind of sediment: a + wrong statement about the skill's invocation mode. The skill started life + with `disable-model-invocation: true`; the owner deliberately made it + model-invoked after live use showed the value is in the agent reaching it + unprompted. Usage section rewritten; the Codex-behaviour paragraph (built on + the manual-only premise) removed. +- **Hard gate contradicted step 4** on inline `CONTEXT.md` capture ("once the + user agrees on the direction" vs "as it happens"). The gate now carries an + explicit exception for additive glossary capture; step 4 owns the rule. +- **Implementation ban deduplicated** — it lived in four places (description, + "Do not use" list, twice inside the gate, stop_condition). The gate is the + single owner: its two internal lists collapsed into one, stop_condition + defers to it. The description keeps its one-line negative trigger and the + "Do not use" list stays — those do invocation routing, not run-time + restraint. +- **Rule/step duplicates collapsed** — minimum-sufficient is owned by the core + rule (step 7 defers); "what NOT to do now" is owned by step 5 Converge (core + rule removed). Same move as the fan-composition prune. +- **README domain list aligned** with the shape-not-domain trigger decision; + 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) + +- **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. + ## v2 — remaining Kept from before: diff --git a/agents/.agents/skills/brainstorm-with-docs/SKILL.md b/agents/.agents/skills/brainstorm-with-docs/SKILL.md index ced3ec4..877adfb 100644 --- a/agents/.agents/skills/brainstorm-with-docs/SKILL.md +++ b/agents/.agents/skills/brainstorm-with-docs/SKILL.md @@ -14,9 +14,11 @@ documentation — not for implementation. -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. +Do NOT change the state of any system until the user has approved a design AND +explicitly asked to implement: no code, config, or infrastructure changes; no +state-changing commands, refactors, data writes, migrations, or deployments; no +invoking an implementation skill; no outward-facing actions other than +read-only lookups. 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 @@ -25,10 +27,9 @@ 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 -documentation files once the user agrees on the direction. It must NOT change the -state of any system: no code, config, or infrastructure changes; no data writes -or migrations; no deployments; and no outward-facing actions other than read-only -lookups. +documentation files once the user agrees on the direction. One documentation +move fires earlier: a NEW glossary term is captured in `CONTEXT.md` inline +during the interview (additive; step 4 owns the rule). If you are unsure whether a command has side effects — especially when querying a live or production system — state what you intend to run and why, and get a yes, @@ -72,7 +73,6 @@ If invoked with arguments, treat `$ARGUMENTS` as the initial problem statement. of the fan live in step 5. * 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. * 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. @@ -228,8 +228,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 minimum-sufficient form — the smallest -that fully preserves the understanding, and no smaller. +matching `artifacts/*.md` file, sized by the minimum-sufficient rule from +``. 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 @@ -276,9 +276,8 @@ interview. 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: +an artifact has been produced. Then STOP — the `` holds until the +user explicitly asks to implement. Offer a small set of next actions, such as: * refine the spec * create or update an ADR