docs(skills): brainstorm-with-docs — правки по холодному ревью

README перестал объявлять скилл ручным: model-invocation — намеренное текущее состояние (триггер — форма задачи, не область). Жёсткий гейт получил исключение для глоссария (спорил с шагом 4) и стал единственным владельцем запрета на реализацию; дубли правил схлопнуты к владельцам. Отложенные находки (шов self_review, критерий конца интервью, версионные пометки в шаблонах) — в Pending decisions ROADMAP. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-01 18:40:38 +03:00
1 parent e3021ce372
commit d10ad6981c
@@ -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 <problem-or-topic>
 ```

-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

@@ -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:
@@ -14,9 +14,11 @@ documentation — not for implementation.

 <hard_gate>

-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 `<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
-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
+`<core_rules>`.

 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.
 <stop_condition>

 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 `<hard_gate>` 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