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/ резолвятся.
2026-06-02 23:23:41 +03:00
1 parent 0a348da22a
commit 50640d8cb5
@@ -0,0 +1,81 @@
 # 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 turns it into 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
 — approval of a design direction is never approval to implement.
 ## Why this exists
 It combines three things that are usually separate:
 - **shared domain language** (glossary / `CONTEXT.md`) and **lightweight ADRs** —
  the discipline of capturing terminology and durable decisions as they crystallise;
 - **active grilling** — not just extracting requirements, but pressure-testing
  them: challenging terms against the glossary, sharpening fuzzy language, probing
  with edge-case scenarios, cross-checking claims against the code;
 - **option exploration** — always comparing 2-3 viable approaches with trade-offs
  before recommending a direction.
 ## Usage
 Invoke manually:
 ```
 /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 keep that disciplined.
 ## Layout
 ```
 brainstorm-with-docs/
 ├── SKILL.md              # the skill: process, rules, grill mechanics
 ├── README.md             # this file
 └── artifacts/            # output templates — read only the one you need
    ├── spec.md           # solution design / engineering spec
    ├── research-note.md  # exploratory, answer not yet known
    ├── adr.md            # lightweight architectural decision record
    ├── runbook.md        # operational procedure
    ├── prd.md            # product-facing behaviour
    └── context.md        # CONTEXT.md glossary format
 ```
 Templates are split per type so the agent loads only what's relevant
 (progressive disclosure).
 ## Roadmap
 - **v1 (current):** working hybrid — context inspection, glossary/ADR discipline,
  active grilling, option comparison, durable artifacts, stop-before-implementation.
 - **v2 (planned):** a *divergence phase* before option synthesis (an
  idea-generation toolkit plus the rule "at least one option the user didn't
  already imply"), a "design for isolation" lens, and fuller multi-context
  support. A `<!-- SEAM -->` marker in `SKILL.md` step 5 marks where it slots in.
 ## Attribution
 This is a derived, original skill — not a copy of either source. It borrows ideas
 from two MIT-licensed projects:
 - **grill-with-docs / grill-me** by Matt Pocock —
  <https://github.com/mattpocock/skills> (MIT, © 2026 Matt Pocock).
  Source of the glossary/`CONTEXT.md` discipline, lightweight ADRs, and the
  active grilling techniques.
 - **brainstorming** by Jesse Vincent (obra), from Superpowers —
  <https://github.com/obra/superpowers> (MIT, © 2025 Jesse Vincent).
  Source of the explore-context → question → compare-options → present-design flow
  and the stop-before-implementation gate.
 The `CONTEXT.md` and ADR formats are adapted from Matt Pocock's `grill-with-docs`
 companion files. Both upstream projects are MIT-licensed; see their repositories
 for full license text.
@@ -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>
@@ -0,0 +1,40 @@
 # ADR — Architectural Decision Record
 ADRs live in `docs/adr/` with sequential numbering: `0001-slug.md`,
 `0002-slug.md`, etc. Create `docs/adr/` lazily — only when the first ADR is
 needed. To number a new one, scan `docs/adr/` for the highest number and add one.
 ## When to offer an ADR
 Offer one only when **all three** are true:
 1. **Hard to reverse** — the cost of changing your mind later is meaningful.
 2. **Surprising without context** — a future reader will look at the code and
   wonder "why on earth did they do it this way?"
 3. **The result of a real trade-off** — there were genuine alternatives and one
   was picked for specific reasons.
 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.
 ## Template
 ```markdown
 # {Short title of the decision}
 {1-3 sentences: what's the context, what we decided, and why.}
 ```
 That's it. An ADR can be a single paragraph. The value is recording *that* a
 decision was made and *why* — not in filling out sections.
 ## Optional sections
 Add these only when they earn their place (most ADRs won't need them):
 - **Status** frontmatter (`proposed | accepted | deprecated | superseded by
  ADR-NNNN`) — useful when decisions get revisited.
 - **Considered options** — only when the rejected alternatives are worth
  remembering (otherwise someone re-proposes them in six months).
 - **Consequences** — only when non-obvious downstream effects need calling out.
@@ -0,0 +1,53 @@
 # CONTEXT.md — Shared Project Language
 `CONTEXT.md` is a **glossary and nothing else**. It exists so that the user, the
 code, and future agents use the same words for the same concepts. It is totally
 devoid of implementation details, decisions, plans, or work logs.
 A single `CONTEXT.md` lives at the repo root. If a `CONTEXT-MAP.md` exists at the
 root, the repo has multiple contexts — read it to find which `CONTEXT.md` the
 current topic belongs to. (Multi-context handling is deliberately light in v1.)
 Create the file lazily — only when the first term is actually worth recording.
 ## Structure
 ```markdown
 # {Context Name}
 {One or two sentences: what this context is and why it exists.}
 ## Language
 **Order**:
 A customer's request to purchase one or more items.
 _Avoid_: Purchase, transaction
 **Invoice**:
 A request for payment sent to a customer after delivery.
 _Avoid_: Bill, payment request
 **Customer**:
 A person or organisation that places orders.
 _Avoid_: Client, buyer, account
 ```
 ## Rules
 - **Be opinionated.** When several words mean the same thing, pick the best one
  and list the rest under `_Avoid_`.
 - **Keep definitions tight.** One or two sentences. Define what it *is*, not what
  it *does*.
 - **Only project-specific terms.** General programming concepts (timeouts, retry,
  cache) don't belong, even if the project uses them heavily. Ask: is this unique
  to this project's domain, or generic? Only the former belongs.
 - **Group under subheadings** when natural clusters emerge; a flat list is fine
  otherwise.
 ## What does NOT go in CONTEXT.md
 - implementation details
 - specs, decisions, or rejected alternatives → spec / ADR
 - operational procedures → runbook
 - validation rules for the current work → spec
 - work logs, temporary notes, speculative ideas
@@ -0,0 +1,38 @@
 # PRD — Product Requirements Document
 Use **only** for product-facing work with user-visible behaviour. For internal
 engineering, infra, or architecture work use `artifacts/spec.md` instead — don't
 force everything into a PRD.
 ## Template
 ```markdown
 # Title
 ## Problem statement
 ## Users
 ## Goals
 ## Non-goals
 ## User stories
 ## Requirements
 ## Out of scope
 ## Success criteria
 ## Open questions
 ```
 ## Notes
 - A PRD describes *what* and *why* from the user's point of view, not *how*. The
  engineering "how" belongs in a spec.
 - **Non-goals** and **Out of scope** are deliberately separate: non-goals are
  things we chose not to optimise for; out of scope is work explicitly deferred.
 - **Success criteria** must be observable — how will we know the behaviour is
  right once shipped?
@@ -0,0 +1,38 @@
 # Research Note
 Use when the work is exploratory and the final answer is not yet known. The
 output is *findings and a direction*, not a committed design.
 When the question is resolved, the research note often graduates into a spec
 (`artifacts/spec.md`) or an ADR (`artifacts/adr.md`).
 ## Template
 ```markdown
 # Title
 ## Question
 ## Context
 ## Known facts
 ## Assumptions
 ## Options / hypotheses
 ## Findings
 ## Recommendation
 ## Remaining unknowns
 ## Next checks
 ```
 ## Notes
 - Keep **Known facts** and **Assumptions** strictly separate. Conflating them is
  how a guess hardens into an unexamined "fact".
 - **Remaining unknowns** and **Next checks** are what make a research note
  useful to the next agent — they say where to dig next.
@@ -0,0 +1,37 @@
 # Runbook
 Use for operational procedures: diagnostics, verification, recovery, deployment,
 or routine maintenance. A runbook is for *doing*, so optimise for someone
 following it under pressure — concrete commands, expected output, clear failure
 branches.
 ## Template
 ```markdown
 # Title
 ## Purpose
 ## When to use
 ## Preconditions
 ## Procedure
 ## Verification
 ## Rollback / recovery
 ## Known failure modes
 ## Notes
 ```
 ## Notes
 - **Procedure** steps should be copy-pasteable where possible, with the expected
  result after each consequential step.
 - **Verification** is how the operator confirms success — not "it should work"
  but "run X, expect Y".
 - **Rollback / recovery** and **Known failure modes** are what separate a
  runbook from a tutorial. If you can't say how to undo it, say that explicitly.
@@ -0,0 +1,56 @@
 # Solution Design / Spec
 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.
 ## Template
 ```markdown
 # Title
 ## Problem
 ## Context
 ## Goals
 ## Non-goals
 ## Current state
 ## Options considered
 ## Recommended approach
 ## Rationale
 ## Decisions and rejected alternatives
 ## Risks and mitigations
 ## Validation
 ## Documentation impact
 ## Open questions
 ```
 ## Notes on key sections
 **Decisions and rejected alternatives** is the highest-value section. Capture:
 - accepted decisions and the reason behind each
 - rejected alternatives and *why* they were rejected
 - subtle constraints and important defaults
 - sequencing decisions
 - assumptions future agents must not silently re-derive
 Do not turn this section into an ADR dump. Promote a decision to its own ADR
 (`artifacts/adr.md`) only when it is durable, surprising, and the result of a
 real trade-off.
 **Validation** describes how we will know the implementation is correct — tests,
 checks, acceptance criteria. It belongs here, not in `CONTEXT.md`.