diff --git a/agents/.agents/skills/brainstorm-with-docs/README.md b/agents/.agents/skills/brainstorm-with-docs/README.md index 828f11b..f839d1a 100644 --- a/agents/.agents/skills/brainstorm-with-docs/README.md +++ b/agents/.agents/skills/brainstorm-with-docs/README.md @@ -70,13 +70,14 @@ Templates are split per type so the agent loads only what's relevant ## Roadmap -- **v1 (current):** working hybrid — context inspection, glossary/ADR discipline, +- **v1:** working hybrid — context inspection, glossary/ADR discipline, 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. +- **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 diff --git a/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md b/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md index 70535a7..4cc2686 100644 --- a/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md +++ b/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md @@ -12,7 +12,11 @@ versioned so it survives across sessions and tools (not just an agent's memory). changes. - **First live test — 2026-06-06.** Real task: Superset dashboard redesign in the clickstream repo (KPI semantics → CONTEXT.md glossary → spec + ADRs). Findings - landed below; the test report drives the v2 section. + landed below; the test report drove the v2 divergence section. +- **Second live test — 2026-08-01.** Wayfinder map «проектирование генератора» + (clickstream-data-platform, map #26): four grilling tickets resolved + fork-by-fork, a fan of options per decision. Landed the whole v2 divergence + block on this evidence (see below). ## Landed (2026-06-06, from first live test) @@ -49,58 +53,62 @@ versioned so it survives across sessions and tools (not just an agent's memory). **brainstorm-with-docs** = repo-grounded option exploration plus durable artifacts. Documented in `README.md`. -## Pending decisions +## Landed (2026-08-01, from second live test) -- **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. +The whole **v2 divergence block** (former proposals 1–6) landed in `SKILL.md`. +Design intent, for the record: the first test's miss was at the *frame* level +("fix the KPI strip" — never "is a KPI dashboard the right vehicle at all?"), +and the user's cost worry made divergence *tiered*, not always-on. What landed: -## v2 (larger) — divergence, informed by the first live test +- **Divergence-then-convergence as separate phases** — step 5 is now "Diverge, + then converge"; the SEAM marker is gone, its intent implemented. Generation + happens before any evaluation. +- **Frame-level divergence** — step 5 opens with a one-sentence restatement of + the user's implicit frame, and the fan must contain ≥1 frame-rejecting option. +- **Tiered divergence** — fan width calibrated to decision weight: minimum fan + for cheap/reversible, toolkit pass for hard-to-reverse/expensive-to-unwind. +- **Idea-generation toolkit with WHEN-triggers** — axis of variation, archetype + stances, inversion, adjacent-domain steal, pre-mortem; null option promoted + out of the toolkit into the mandatory minimum fan (cheap win). +- **Cheap wins** — null option + frame restatement are now unconditional. +- **Diversity self-check** — "different kinds or variations of one?" check + before presenting. +- **Fork-in-place grilling** (new, from the test, not in the old proposals) — + step 4: when the interview hits a decision fork, run the divergence pass on it + immediately and wait for the user's reaction before moving on; invite + reactions to rejected options, not just the favourite. Converge carries + rejected options + reasons into the resolution record. +- **F5a** — `docs/agents/*.md` added to the step-1 read list. +- **Same-day prune** (writing-great-skills review): step 5 is the single owner + of fan composition — the F1 core rule keeps only the generate-before-judging + principle, and the repo-side `AGENTS.md` line routes without restating the + fan. Description halved to two trigger branches (ambiguous problem / decision + fork); the "Use for" list collapsed from nine bullets to four. Domain + enumeration dropped from the triggers entirely (user's call): the *shape* — + unclear direction, decision fork — is the trigger, not the field, and a + domain list only gave the router reasons not to fire (e.g. course-content + or skill-design forks). -**Motivating failure from the test.** The dashboard brainstorm converged on "fix -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. The landed F1 rule now adds a cheap frame-challenger every time; -v2 is about when to spend more effort on full divergent exploration. +**Evidence from the second test.** Twice the winning answer came from *outside* +the initially presented fan, after the user pushed against its frame: +DDL-autogeneration reframed into a data contract owned by the generator (ticket +#29), and a git-stored snapshot reframed into manifest-only-in-git (ticket #30). +Pattern worth keeping in mind for future revisions: the fan's value is not only +its options — presenting it invites the owner to break the frame themselves. +Per-question recommendations (R1) confirmed again as the main driver. -**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 -pays. +**Routing gap, found and fixed.** Nothing routed grilling/wayfinder sessions to +this skill except a per-map Notes line and one agent's private memory — fragile +and machine-local. Fixed two ways: (a) the skill `description` now names +decision-fork grilling (incl. the Russian trigger word «развилка») so the +skill router matches it; (b) a repo-side routing line in the project's +`AGENTS.md` (clickstream-data-platform) — deterministic, versioned, copyable to +future repos. The third-party grilling skill stays unforked; this skill owns +the fan practice. -Proposals (priority order): +## v2 — remaining -1. **Tiered divergence (cost control).** Calibrate divergence effort to decision - 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 - (one sentence), catches frame-lock that F1 misses. -3. **Divergence-then-convergence as separate phases (the SEAM intent).** Generate - diverse options FIRST without evaluating, THEN judge/recommend. Mixing - generation and evaluation self-censors weird options before they're voiced. - Structural change, not just a rule. -4. **Idea-generation toolkit**, each technique with a WHEN-trigger so the agent - knows when to reach for it: - - *axis of variation* — name the 1–2 dimensions options vary along; ensure they - don't all sit on one axis. - - *archetype stances* — force an MVP / a robust / a radical option. - - *inversion* — "what if we did the opposite of the obvious?" - - *steal-from-adjacent-domain* — how does another field solve this? - - *pre-mortem* — "assume the chosen option failed in 6 months; what option would - we wish we'd considered?" - - *null option* — "what if we don't build it / do nothing?" -5. **Cheap wins (80/20, can land before the full toolkit):** always include the - null option + the one-sentence frame restatement. Near-zero cost, catch most - frame/convergence failures. -6. **Diversity self-check before presenting:** "Are these genuinely different kinds - of answer, or variations of one? If variations, generate one more from a - different axis." A cheap critic that enforces F1 harder. - -Also kept from before: +Kept from before: - **"Design for isolation / clarity" lens** (from superpowers brainstorming): evaluate options by whether each unit has one clear purpose and a clean diff --git a/agents/.agents/skills/brainstorm-with-docs/SKILL.md b/agents/.agents/skills/brainstorm-with-docs/SKILL.md index 85c93ac..ced3ec4 100644 --- a/agents/.agents/skills/brainstorm-with-docs/SKILL.md +++ b/agents/.agents/skills/brainstorm-with-docs/SKILL.md @@ -1,6 +1,6 @@ --- 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 reaching shared understanding and a recommended direction. Use when exploring an ambiguous engineering, DevOps, architecture, migration, integration, research, or documentation problem; the understanding is the deliverable, recorded in the smallest durable artifact (spec, ADR, runbook, research note, or CONTEXT.md glossary update). Not for implementation, trivial fixes, or executing an already-approved plan. +description: Brainstorm and align on a design, grounded in the project's existing docs and vocabulary. Use when exploring an ambiguous problem — whatever the domain — or when grilling a decision fork (развилка): a fan of options, then convergence. The understanding is the deliverable, recorded in the smallest durable artifact (spec, ADR, runbook, research note, CONTEXT.md). Not for implementation, trivial fixes, or executing an already-approved plan. 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:*) --- @@ -41,12 +41,10 @@ not. 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 +* ambiguous problems with an unclear direction — the shape is the trigger, + not the domain +* choosing between approaches or grilling a decision fork: one decision at a + time, a fan of options before converging * converting a discussion into a durable specification * clarifying project terminology and assumptions @@ -69,11 +67,9 @@ If invoked with arguments, treat `$ARGUMENTS` as the initial problem statement. * 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. -* Offer 2-3 viable approaches within the user's framing, plus at least one (more - if useful) that challenges the framing itself — the null option, a reframe, an - adjacent-domain steal. Without the framing-challenger, options collapse into - variations of one idea. Don't pad to hit a number; every option must be - genuinely distinct. +* Generate the full fan of options before judging any of it — options of + genuinely different kinds, not variations of one idea. Composition and width + of the fan live in step 5. * 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. @@ -99,7 +95,7 @@ If invoked with arguments, treat `$ARGUMENTS` as the initial problem statement. Before asking the user anything, read the relevant context. Prefer this order: -1. `AGENTS.md` or an equivalent project map +1. `AGENTS.md` or an equivalent project map, plus `docs/agents/*.md` if present 2. README / project overview 3. `docs/`, then existing specs and design docs 4. ADRs (`docs/adr/`), runbooks, status docs @@ -171,18 +167,50 @@ risk), using the format in [artifacts/context.md](artifacts/context.md) — don' batch them. Redefining an already-documented term is a vocabulary change: propose it inline, but confirm before writing (see step 6). -## 5. Synthesize options +When the interview hits a genuine decision fork — a choice that shapes what +comes after — resolve it in place rather than deferring it to the end: run a +divergence pass on that fork (see step 5), sized to its weight, and wait for the +user's reaction before moving on. Invite reactions to the options you'd reject, +not just to the favourite: what the user says about a rejected option often +sharpens what they actually want. - +## 5. Diverge, then converge -Present 2-3 viable approaches within the user's framing, plus at least one that -challenges it. 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 +Two passes, kept separate: first generate options without judging them, then +evaluate. Mixing generation and evaluation censors unusual options before +they're voiced. + +**Diverge.** Restate the user's implicit frame in one sentence — the assumption +their question stands on. Then lay out the fan: + +* 2-3 genuinely distinct approaches within the frame; +* at least one option that rejects the frame itself; +* the null option — what happens if this isn't done at all. + +Size the fan to the decision's weight. For a cheap, reversible choice the list +above is enough; for a hard-to-reverse or expensive-to-unwind one, widen it with +the toolkit — each technique carries its trigger: + +* *axis of variation* — options all sit on one axis? Name the axis, add an + option from a different one. +* *archetype stances* — fan feels timid or samey? Force an MVP, a robust, and a + radical option. +* *inversion* — one obvious approach dominates? Add its opposite. +* *steal from an adjacent domain* — problem feels novel? Ask how another field + solves it. +* *pre-mortem* — stakes are high? Assume the favourite failed in six months; + add the option you'd wish you'd considered. + +Before presenting, self-check: are these different *kinds* of answer, or +variations of one? If variations, generate one more from a different axis. + +**Converge.** For each option: 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. +not do now. When the fork is resolved, carry the rejected options and the +reasons for rejecting them into the resolution record (the spec's alternatives, +the ADR's options considered). ## 6. Confirm direction