docs(skills): brainstorm-with-docs — дивергенция v2: веер, развилки, маршрутизация
Приземлён блок дивергенции из ROADMAP по итогам второго живого теста (wayfinder-карта #26 стенда): шаг 5 разделён на веер и конвергенцию, ширина веера — по весу решения, развилки решаются по месту в интервью. Триггер «развилка» в description; описание и правила подрезаны по ревью writing-great-skills. Свидетельства и доводы — в ROADMAP.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
10d0003e10
commit
e3021ce372
3 files changed
+111
-74
No files matched your search
@@ -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
|
||||
|
||||
Reference in new issue
Block a user