docs(brainstorm-with-docs): обновлена документация скилла
- Зачем: - 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.
This commit is contained in:
Dmitry Dementiev committed
1 parent
a1fe4ce319
commit
14adf77424
3 files changed
+43
-101
No files matched your search
@@ -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 `<hard_gate>` 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 `<!-- SEAM -->` 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.
|
||||
@@ -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 `<!-- SEAM -->` 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 `<!-- SEAM -->` 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 —
|
||||
<https://github.com/mattpocock/skills> (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 —
|
||||
<https://github.com/obra/superpowers> (MIT, © 2025 Jesse Vincent).
|
||||
Source of the explore-context → question → compare-options → present-design flow
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user