From 14adf774240628ab96947c2d1d30f6868c3ac32a Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Sat, 6 Jun 2026 17:26:57 +0300 Subject: [PATCH] =?UTF-8?q?docs(brainstorm-with-docs):=20=D0=BE=D0=B1?= =?UTF-8?q?=D0=BD=D0=BE=D0=B2=D0=BB=D0=B5=D0=BD=D0=B0=20=D0=B4=D0=BE=D0=BA?= =?UTF-8?q?=D1=83=D0=BC=D0=B5=D0=BD=D1=82=D0=B0=D1=86=D0=B8=D1=8F=20=D1=81?= =?UTF-8?q?=D0=BA=D0=B8=D0=BB=D0=BB=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - README и ROADMAP должны отражать текущую модель скилла без устаревшего handoff. - Что: - удален временный DEV-HANDOFF.md. - README уточняет отличие от grill-me и роль grill-with-docs как upstream influence. - ROADMAP фиксирует R2/F4 как landed и описывает F1 как cheap frame-challenger. - Проверка: - git diff --check -- agents/.agents/skills/brainstorm-with-docs. --- .../brainstorm-with-docs/DEV-HANDOFF.md | 75 ------------------- .../skills/brainstorm-with-docs/README.md | 35 ++++++--- .../skills/brainstorm-with-docs/ROADMAP.md | 34 +++++---- 3 files changed, 43 insertions(+), 101 deletions(-) delete mode 100644 agents/.agents/skills/brainstorm-with-docs/DEV-HANDOFF.md diff --git a/agents/.agents/skills/brainstorm-with-docs/DEV-HANDOFF.md b/agents/.agents/skills/brainstorm-with-docs/DEV-HANDOFF.md deleted file mode 100644 index 95ce585..0000000 --- a/agents/.agents/skills/brainstorm-with-docs/DEV-HANDOFF.md +++ /dev/null @@ -1,75 +0,0 @@ -# Dev handoff — brainstorm-with-docs - -Resume context for a fresh agent working on **this skill's development**. -Dev-phase only; remove before the skill stabilises. For the backlog and decisions -see [ROADMAP.md](ROADMAP.md); don't duplicate it here. - -## What this is - -A custom, manually-invoked skill that fuses Matt Pocock's `grill-with-docs` -(glossary/`CONTEXT.md` + lightweight ADRs + active grilling) with obra/superpowers -`brainstorming` (explore → question → compare options → recommend → design doc), -tailored to the user. It is for thinking/alignment/documentation, never -implementation. See `SKILL.md`, `README.md`, and `artifacts/*.md` for the result. - -Source files on disk (for comparison / not to be copied wholesale): -- `~/.claude/skills/grill-with-docs/{SKILL.md,CONTEXT-FORMAT.md,ADR-FORMAT.md}` -- `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.7/skills/brainstorming/SKILL.md` - -## State - -- v1 shipped + reviewed. Commits `50640d8`, `f24b342` (pushed to origin/master). -- Repo path: `~/dotfiles/agents/.agents/skills/brainstorm-with-docs/`, symlinked - into `~/.claude/skills/` (stow). Codex has a *separate* skills dir; this skill - is not yet shared there. -- Cross-session memory: `project_brainstorm_with_docs.md` (in the agent's memory - dir, indexed from MEMORY.md). The in-repo `ROADMAP.md` is now the canonical - roadmap; memory is a pointer. - -## Non-obvious rationale (the "why", not re-derivable from the files) - -- **Frontmatter is portability-driven.** Claude reads all fields; Codex reads - ONLY `name` + `description` (verified from Codex's own skill-creator). So extra - fields are kept only when "useful on Claude, inert on Codex." `disallowed-tools` - was removed — it's ineffective even on Claude (clears after the next message). - `allowed-tools` space-separated is valid (Claude docs); it is pre-approval, not - a restriction. Don't reopen this (= rejected finding F6 in ROADMAP). -- **The gate is the real control, not the harness.** User runs agents in auto - mode, where permission prompts are unreliable. So `` is written to be - self-enforcing ("don't rely on the harness; announce before touching live - systems") and allows investigation (read + read-only cmds + web research) while - forbidding state changes. -- **`disable-model-invocation: true` is intentional** even though the user said - "mostly manual" — for an *interview* skill, surprise auto-activation is more - annoying than helpful; predictable manual invocation fits better. -- **Agile by design.** v1 = "boring-correct working hybrid"; the novel - divergence mechanics are deferred to v2 on purpose, with a `` at - `SKILL.md` step 5 kept self-contained so v2 slots in without restructuring. - -## Open threads (decide with the user) - -All tracked in `ROADMAP.md`. Most live ones: -- **R1** — restore grill's "give a recommended answer with each question" (likely - accidental drop in v1). User leaning yes; deciding whether to do it now or after - the first live test. -- **R2 / F1** — interview relentlessness + the divergence one-liner are held back - on purpose so the first live test shows the pure-convergence baseline. -- **F4** — decide how `brainstorm-with-docs` and `grill-with-docs` coexist. - -## Immediate next step - -The user runs the **first live test on real tasks** next. Capture observations -(does it under-grill? do options collapse into one idea? is multi-context missed?) -and feed them into the R1/R2/F1 decisions. Append findings to this file or -`ROADMAP.md` as you go. - -## Suggested skills - -- **brainstorm-with-docs itself** — dogfood it; refining it is exactly a - design/documentation problem. -- **write-a-skill** — sanity-check SKILL.md structure/frontmatter on changes. -- **grill-with-docs** — reference to check no valuable mechanic was lost (this is - how R1/R2 were found). -- **conventional-commits** — required for any commit here (commits are in Russian, - `type(scope): …` + Зачем/Что/Проверка body). -- **handoff** — refresh this file when a session produces a new stable state. diff --git a/agents/.agents/skills/brainstorm-with-docs/README.md b/agents/.agents/skills/brainstorm-with-docs/README.md index fa21943..a16dfd3 100644 --- a/agents/.agents/skills/brainstorm-with-docs/README.md +++ b/agents/.agents/skills/brainstorm-with-docs/README.md @@ -12,15 +12,25 @@ proposes documentation, but stops before code, config, or infrastructure changes ## Why this exists -It combines three things that are usually separate: +It combines four 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. +- **option exploration** — comparing 2-3 viable approaches within the user's + framing, plus at least one framing-challenger so the agent does not only + optimise inside the first shape of the problem; +- **durable output** — turning the useful thinking into the smallest appropriate + artifact: glossary entry, spec, ADR, runbook, research note, or PRD. + +The closest day-to-day comparison is `grill-me`: use `grill-me` when you mainly +want the agent to pull understanding out of you and align on a plan in the +conversation. Use `brainstorm-with-docs` when the discussion must be grounded in +the repository and leave behind project documentation. `grill-with-docs` is an +upstream influence for glossary and ADR discipline, but this skill is not trying +to follow that methodology wholesale. ## Usage @@ -59,15 +69,16 @@ Templates are split per type so the agent loads only what's relevant ## 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 `` marker in `SKILL.md` step 5 marks where it slots in. + active grilling, option comparison with an additive framing-challenger, durable + artifacts, stop-before-implementation. +- **v2 (planned):** tiered fuller divergence for heavier decisions, an + idea-generation toolkit, a "design for isolation" lens, and fuller + multi-context support. A `` marker in `SKILL.md` step 5 marks where + it slots in. See [ROADMAP.md](ROADMAP.md) for the full backlog, pending decisions, and what -has been considered and rejected. (Dev-phase docs — `ROADMAP.md` and any -`DEV-HANDOFF.md` — can be removed once the skill stabilises.) +has been considered and rejected. `ROADMAP.md` is development memory and can be +removed once the skill stabilises. ## Attribution @@ -77,7 +88,9 @@ from two MIT-licensed projects: - **grill-with-docs / grill-me** by Matt Pocock — (MIT, © 2026 Matt Pocock). Source of the glossary/`CONTEXT.md` discipline, lightweight ADRs, and the - active grilling techniques. + active grilling techniques. This skill deliberately diverges from + `grill-with-docs` where the user's workflow needs broader artifact creation and + option exploration. - **brainstorming** by Jesse Vincent (obra), from Superpowers — (MIT, © 2025 Jesse Vincent). Source of the explore-context → question → compare-options → present-design flow diff --git a/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md b/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md index 542e635..70535a7 100644 --- a/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md +++ b/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md @@ -35,19 +35,22 @@ versioned so it survives across sessions and tools (not just an agent's memory). Rationale moved here; `SKILL.md` now carries only a neutral marker. *Principle: the shipped skill must not tell a running agent what result the author expects.* (New finding, not previously in backlog.) - -## Pending decisions - - **R2 — interview relentlessness. Verdict: leave SOFT.** In the live test the interview ran long because the *user* kept opening new forks, not from over-asking. The real value came from data/code cross-referencing ("never ask - what the repo can answer — search first"), not relentlessness. Keep - `grill-with-docs` for hard pressure-testing (see F4). -- **F4 — relationship to `grill-with-docs`.** Live-test boundary that worked: - **brainstorm** = when you need *options* and a direction (divergence→convergence); - **grill** = when you have *one* plan to pressure-test against docs. Action: - document this when-to-use-which in `README.md` (not supersede — not a strict - superset; lacks full multi-context). + what the repo can answer — search first"), not relentlessness. For pure + conversation-only alignment, use `grill-me`; this skill stays softer because it + must also inspect context and produce artifacts. +- **F4 — comparison target clarified.** `grill-with-docs` is an upstream + influence, not the main operational sibling: it is intentionally shaped by + someone else's methodology and was too narrow for the user's documentation + needs. The practical boundary is now with `grill-me`: **grill-me** = pull + understanding from the user and sync with the agent, without creating docs; + **brainstorm-with-docs** = repo-grounded option exploration plus durable + artifacts. Documented in `README.md`. + +## Pending decisions + - **F5a — read `docs/agents/*.md` in step 1.** Confirmed by the test: `AGENTS.md` / ADRs were the key map (the doc-layout policy lived there, and reversing it needed that context). Add to the step-1 read list. @@ -58,8 +61,8 @@ versioned so it survives across sessions and tools (not just an agent's memory). the KPI strip" and never generated the option "maybe a KPI dashboard isn't the best teaching vehicle at all" (a guided SQL notebook? a before/after comparison? a deliberately-broken dashboard to fix?). The miss was at the **frame** level, not -the option level — F1 helps within the frame but doesn't question the frame -itself. v2 must address both levels. +the option level. The landed F1 rule now adds a cheap frame-challenger every time; +v2 is about when to spend more effort on full divergent exploration. **Core tension (raised by the user).** Full divergence is time-expensive but high-value. So v2 must be **tiered, not always-on** — spend divergence where it @@ -68,9 +71,10 @@ pays. Proposals (priority order): 1. **Tiered divergence (cost control).** Calibrate divergence effort to decision - weight at step 3 (scope). Trivial/reversible → F1 only (one non-implied - option). Heavy/irreversible/expensive-to-unwind → full toolkit pass. Directly - answers the cost worry: divergence proportional to rollback cost. + weight at step 3 (scope). Trivial/reversible → current F1 only (2-3 framed + options plus one framing-challenger). Heavy/irreversible/expensive-to-unwind → + full toolkit pass. Directly answers the cost worry: divergence proportional to + rollback cost. 2. **Frame-level divergence (the test gap).** Before listing options, state the user's implicit frame in one sentence, then generate ≥1 option that rejects that frame. "Why a KPI dashboard at all?" is the poster example. Near-zero cost