feat(skills): добавлен скилл brainstorm-with-docs (v1)
- Зачем:
- нужен ручной скилл для брейнсторма и дизайна, который удерживает
словарь смыслов (CONTEXT.md) и лёгкие ADR, активно прожаривает план
и не сваливается в реализацию.
- Что:
- SKILL.md: процесс (контекст → классификация → декомпозиция →
грилл → синтез опций → подтверждение → артефакт), единый HARD-GATE
«исследуй, но не меняй состояние» с поправкой на auto mode.
- artifacts/: шаблоны spec, research-note, adr, runbook, prd, context
(по файлу на тип для progressive disclosure).
- README.md с MIT-атрибуцией grill-with-docs (Pocock) и brainstorming
(obra/superpowers); шов для будущей фазы дивергенции в шаге 5.
- frontmatter переносим: Claude читает все поля, Codex — name+description.
- Проверка:
- python3 yaml-парс frontmatter; markdown-ссылки на artifacts/ резолвятся.
This commit is contained in:
ddadmin committed
1 parent
0a348da22a
commit
50640d8cb5
8 files changed
+572
No files matched your search
@@ -0,0 +1,229 @@
|
||||
---
|
||||
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.
|
||||
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:*)
|
||||
---
|
||||
|
||||
# Brainstorm With Docs
|
||||
|
||||
Move the user from an unclear problem to shared understanding, clear project
|
||||
language, viable options, a recommended direction, and the smallest useful
|
||||
durable documentation artifact. This skill is for thinking, alignment, and
|
||||
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.
|
||||
|
||||
Approval of a design direction is NOT approval to implement. After producing or
|
||||
updating the agreed documentation artifact, STOP.
|
||||
|
||||
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.
|
||||
|
||||
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,
|
||||
before running it. Do not rely on the harness to stop you; in auto mode it may
|
||||
not.
|
||||
|
||||
</hard_gate>
|
||||
|
||||
<what_to_do>
|
||||
|
||||
Use this skill for:
|
||||
|
||||
* ambiguous engineering tasks
|
||||
* architecture or design decisions
|
||||
* DevOps and infrastructure work
|
||||
* research-heavy technical tasks
|
||||
* migration, integration, or operational-procedure design
|
||||
* choosing between implementation approaches
|
||||
* converting a discussion into a durable specification
|
||||
* clarifying project terminology and assumptions
|
||||
|
||||
Do not use this skill for:
|
||||
|
||||
* tiny mechanical edits or straightforward bug fixes with an obvious cause
|
||||
* simple code generation
|
||||
* pure execution of an already-approved plan
|
||||
* cases where the user explicitly asks to skip discussion and implement
|
||||
|
||||
If invoked with arguments, treat `$ARGUMENTS` as the initial problem statement.
|
||||
|
||||
</what_to_do>
|
||||
|
||||
<core_rules>
|
||||
|
||||
* Ask one question at a time when interviewing; wait for the answer.
|
||||
* Never ask for something the repository can answer — search first.
|
||||
* Prefer project-specific language over generic terminology.
|
||||
* Surface assumptions, constraints, risks, trade-offs, and non-goals.
|
||||
* Don't interview forever — when the problem, constraints, and success criteria
|
||||
are clear enough, stop asking and synthesize.
|
||||
* Always consider 2-3 viable approaches before recommending one.
|
||||
* 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.
|
||||
* Keep `CONTEXT.md` strictly a glossary; create ADRs only sparingly.
|
||||
* Do not produce a detailed implementation plan unless the user asks for one.
|
||||
|
||||
</core_rules>
|
||||
|
||||
<how_to_do_it>
|
||||
|
||||
## 1. Inspect project context
|
||||
|
||||
Before asking the user anything, read the relevant context. Prefer this order:
|
||||
|
||||
1. `AGENTS.md` or an equivalent project map
|
||||
2. README / project overview
|
||||
3. `docs/`, then existing specs and design docs
|
||||
4. ADRs (`docs/adr/`), runbooks, status docs
|
||||
5. code and config relevant to the problem
|
||||
|
||||
Look for: existing terminology, decisions already made, known constraints,
|
||||
previously rejected options, deployment model, testing/validation conventions,
|
||||
and patterns the solution should follow. Respect a documented structure if one
|
||||
exists. If no context is available, say so and continue with what the user gives.
|
||||
|
||||
## 2. Classify the work and pick the likely artifact
|
||||
|
||||
Decide what kind of work this is, then which artifact is likely to fit:
|
||||
|
||||
* answer still unknown → [research note](artifacts/research-note.md)
|
||||
* direction chosen, not yet built → [spec / solution design](artifacts/spec.md)
|
||||
* durable, surprising, hard-to-reverse trade-off → [ADR](artifacts/adr.md)
|
||||
* operational procedure / recovery / diagnostics → [runbook](artifacts/runbook.md)
|
||||
* shared project vocabulary → [`CONTEXT.md` glossary](artifacts/context.md)
|
||||
* product-facing, user-visible behaviour → [PRD](artifacts/prd.md)
|
||||
|
||||
Don't force everything into a PRD. Read an artifact's file only when you're
|
||||
actually about to write that kind of artifact.
|
||||
|
||||
## 3. Check scope and decompose if needed
|
||||
|
||||
Before deep brainstorming, check whether this is one coherent problem or several.
|
||||
If it's too broad, pause and propose a decomposition — separating research from
|
||||
implementation, design from execution, product requirements from engineering
|
||||
design, one-time setup from recurring operations, reversible from hard-to-reverse
|
||||
decisions. Ask which part to handle first.
|
||||
|
||||
## 4. Interview / grill
|
||||
|
||||
Interview the user until the problem is clear enough to synthesize. One question
|
||||
at a time. When the reason for a question isn't obvious, briefly say why it
|
||||
matters. Prefer questions that clarify: the actual problem and why it matters,
|
||||
expected outcome, who is affected, constraints, non-goals, success criteria,
|
||||
failure modes, operational and security risks, reversibility, deadlines or
|
||||
sequencing, what's been tried, and what must not change.
|
||||
|
||||
Grill actively — don't just collect answers, pressure-test them:
|
||||
|
||||
* **Challenge against the glossary.** If a term conflicts with `CONTEXT.md`, call
|
||||
it out: "Your glossary defines 'cancellation' as X, but you mean Y — which?"
|
||||
* **Sharpen fuzzy language.** Propose a precise canonical term for vague or
|
||||
overloaded words: "You say 'account' — Customer or User? Those differ."
|
||||
* **Probe with concrete scenarios.** Invent edge cases that force precision about
|
||||
the boundaries between concepts.
|
||||
* **Cross-reference with code.** When the user states how something works, check
|
||||
the code agrees; surface contradictions: "Your code cancels whole Orders, but
|
||||
you said partial cancellation is possible — which is right?"
|
||||
|
||||
Capture resolved terms in `CONTEXT.md` inline, as they happen, using the format
|
||||
in [artifacts/context.md](artifacts/context.md) — don't batch them.
|
||||
|
||||
## 5. Synthesize options
|
||||
|
||||
<!-- SEAM: v2 will prepend a divergence phase (idea-generation toolkit +
|
||||
"at least one option the user didn't already imply") before this
|
||||
convergence step. Keep this step self-contained so it can be split. -->
|
||||
|
||||
Present 2-3 viable approaches. For each: short description, when it fits,
|
||||
benefits, trade-offs, risks, operational implications, documentation impact, and
|
||||
what it avoids or postpones. Then recommend one, explaining why it fits the
|
||||
constraints, what risks remain, what to validate first, and what to explicitly
|
||||
not do now.
|
||||
|
||||
## 6. Confirm direction
|
||||
|
||||
Before writing or changing durable project documents, confirm the direction.
|
||||
Confirmation can be lightweight, e.g.:
|
||||
|
||||
> "I recommend option B. I'd document it as a solution design, add one
|
||||
> lightweight ADR for the storage-layout decision, and add two terms to
|
||||
> `CONTEXT.md`. Does that match your intent?"
|
||||
|
||||
Don't ask permission for every wording choice, but DO confirm before: creating a
|
||||
spec, creating an ADR, changing architectural direction, or changing documented
|
||||
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.
|
||||
|
||||
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
|
||||
`docs/adr/`, and other artifacts under `docs/` (e.g. `docs/specs/`,
|
||||
`docs/runbooks/`). If the location isn't obvious, propose a path and confirm it
|
||||
as part of step 6 rather than guessing. Create directories lazily.
|
||||
|
||||
Then go to `<validation>` and `<stop_condition>`.
|
||||
|
||||
</how_to_do_it>
|
||||
|
||||
<shared_project_language>
|
||||
|
||||
`CONTEXT.md` is only for shared project language: domain terms, project-specific
|
||||
concepts, preferred names, terms to avoid, and short relationships between
|
||||
concepts when they clarify language. It is a glossary, not a spec, work log, ADR
|
||||
store, validation plan, or list of rejected alternatives.
|
||||
|
||||
While interviewing, watch for terms that are ambiguous, overloaded, used
|
||||
inconsistently, or missing from shared docs. If a durable term matters to future
|
||||
work, propose adding it. Full format and rules: [artifacts/context.md](artifacts/context.md).
|
||||
|
||||
If something is a decision → spec or ADR. If it's an operational procedure →
|
||||
runbook. If it's a validation rule for this work → the spec.
|
||||
|
||||
</shared_project_language>
|
||||
|
||||
<validation>
|
||||
|
||||
Before presenting the final artifact, review it for: unclear terms, missing
|
||||
constraints, hidden assumptions, contradictions with existing docs, unnecessary
|
||||
scope expansion, premature implementation detail, missing validation criteria,
|
||||
decisions that should (or should not) be ADRs, operational steps that should be a
|
||||
runbook, and context that does (or does not) belong in `CONTEXT.md`.
|
||||
|
||||
If it's too large, propose splitting it. If it's too vague, continue the
|
||||
interview.
|
||||
|
||||
</validation>
|
||||
|
||||
<stop_condition>
|
||||
|
||||
After the artifact is produced, 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:
|
||||
|
||||
* refine the spec
|
||||
* create or update an ADR
|
||||
* update `CONTEXT.md`
|
||||
* create a runbook
|
||||
* derive a compact implementation checklist
|
||||
* start implementation (only on explicit request)
|
||||
|
||||
Do not proceed automatically.
|
||||
|
||||
</stop_condition>
|
||||
Reference in new issue
Block a user