docs(skills): brainstorm-with-docs — правки по холодному ревью
README перестал объявлять скилл ручным: model-invocation — намеренное текущее состояние (триггер — форма задачи, не область). Жёсткий гейт получил исключение для глоссария (спорил с шагом 4) и стал единственным владельцем запрета на реализацию; дубли правил схлопнуты к владельцам. Отложенные находки (шов self_review, критерий конца интервью, версионные пометки в шаблонах) — в Pending decisions ROADMAP. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
e3021ce372
commit
d10ad6981c
3 files changed
+70
-39
No files matched your search
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user