dotfiles/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md

# Roadmap & backlog — brainstorm-with-docs

Single source of truth for what's done, pending, and deferred. In-repo and
versioned so it survives across sessions and tools (not just an agent's memory).

## Status

- **v1 — shipped.** Commits `50640d8` (initial) and `f24b342` (review fixes).
  Working hybrid: context inspection, glossary/`CONTEXT.md` + lightweight ADR
  discipline, active grilling, option comparison, durable artifacts, and a
  stop-before-implementation gate that allows investigation but forbids state
  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 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)

- **R1 — recommend-an-answer-per-question — RESTORED** (`SKILL.md` step 4).
  Evidence: per-question recommendations drove nearly every decision in the test;
  bare questions would have been flat. The user confirmed the recommendation was
  what he leaned on ("often hits the mark").
- **F1 — divergence — ADDED** as a `<core_rule>` (and echoed in step 5). Final
  form after discussion: offer 2-3 approaches *within* the framing **plus** at
  least one (more if useful) that *challenges* the framing — the divergent option
  is additive, not a stolen slot — with an explicit "don't pad to a number" guard.
  Evidence: in the test, 2 of 3 options were variations of one idea; only the
  consciously-pushed third was a different *kind* of answer. Rationale for keeping
  it mandatory (not "preferably"): the user is the final filter, so a weak
  divergent option costs ~nothing, but a *missing* one is invisible and can't be
  picked or rewritten.
- **SEAM-bias — FIXED.** The verbose `SEAM/TODO` comment in `SKILL.md` step 5
  primed the running agent with the expected outcome ("we want to see how badly
  pure convergence collapses") — contaminating the very observation it wanted.
  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.)
- **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. 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`.

## Landed (2026-08-01, from second live test)

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:

- **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).

**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.

**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.

## Landed (2026-08-01, from cold review)

A fresh-session reviewer (no shared context, writing-great-skills lens) read
the skill cold. Applied same day:

- **README "manual-only" claim was stale** — the worst kind of sediment: a
  wrong statement about the skill's invocation mode. The skill started life
  with `disable-model-invocation: true`; the owner deliberately made it
  model-invoked after live use showed the value is in the agent reaching it
  unprompted. Usage section rewritten; the Codex-behaviour paragraph (built on
  the manual-only premise) removed.
- **Hard gate contradicted step 4** on inline `CONTEXT.md` capture ("once the
  user agrees on the direction" vs "as it happens"). The gate now carries an
  explicit exception for additive glossary capture; step 4 owns the rule.
- **Implementation ban deduplicated** — it lived in four places (description,
  "Do not use" list, twice inside the gate, stop_condition). The gate is the
  single owner: its two internal lists collapsed into one, stop_condition
  defers to it. The description keeps its one-line negative trigger and the
  "Do not use" list stays — those do invocation routing, not run-time
  restraint.
- **Rule/step duplicates collapsed** — minimum-sufficient is owned by the core
  rule (step 7 defers); "what NOT to do now" is owned by step 5 Converge (core
  rule removed). Same move as the fan-composition prune.
- **README domain list aligned** with the shape-not-domain trigger decision;
  README Roadmap section reduced to a pointer at this file (it had become a
  second source of truth).

## Landed (2026-08-01, step 7 / self_review seam resolved)

The cold review caught that `<self_review>` ran "before presenting" but *after*
the file was written — order unstated, and a review verdict of "continue the
interview" left a half-baked artifact on disk with no instructions. Resolution,
shaped by three inputs:

- **Upstream comparison** (owner's call to check Matt Pocock's current skills):
  Matt has no post-write review at all — `domain-modeling` writes glossary/ADRs
  inline as terms resolve ("don't batch"; our gate exception for inline capture
  independently converged on this), and `to-spec` synthesizes from the
  conversation with its only checkpoint *before* the write. Pattern: validate
  before writing; the write itself is linear.
- **Owner's size nuance:** artifacts can be large — a full draft pass through
  the chat before writing would push the whole text through context twice. So
  the pre-write review runs on the artifact *plan* (outline + key content
  decisions); the checklist is decision-altitude anyway, only "unclear terms"
  is wording-level.
- **Owner's experience:** a cheap re-read of the finished document by its own
  author regularly finds real defects. Kept, as a second tier.

Landed shape — two tiers: `<self_review>` runs at step 6 on the plan (can send
the run back to the interview; no file exists yet), step 7 writes the file once
directly, then re-reads it end-to-end as a reader. Unlike upstream, the review
itself is kept — `to-spec` has none; ours has content worth keeping.

Follow-up (same day): the re-read's reaction now splits by the level of the
find. Text-level — fix in place, silently. Decision-level (contradiction with
docs or between sections, coverage hole, unhandled scenario) — present to the
user, neither silently fixed nor suppressed. Owner's evidence: text-level finds
are visible and harmless, but contradictions caught on re-read have mattered
more than once; a flat "don't reopen decisions" ban would force the agent to
either suppress such a find or fix it past the owner.

## v2 — remaining

Kept from before:

- **"Design for isolation / clarity" lens** (from superpowers brainstorming):
  evaluate options by whether each unit has one clear purpose and a clean
  interface.
- **Fuller multi-context.** v1 handles a single root `CONTEXT.md` and only
  mentions `CONTEXT-MAP.md`. Restore grill-with-docs's full model: `CONTEXT-MAP.md`
  + per-context `CONTEXT.md` + per-context `docs/adr/` + a Relationships section.

## Rejected (do not revisit without new evidence)

- **F6 — "space-separated `allowed-tools` won't parse."** False. Claude Code docs
  accept space- or comma-separated or YAML list; and `allowed-tools` is
  pre-approval, not a restriction. No change needed.
- **Hard interview-stop checklist** (cold-review finding, 2026-08-01). Proposal:
  replace "clear enough to synthesize" with a checkable triple (problem,
  constraints, success criteria named + no open forks). Owner's call: keep it
  soft — a hard checklist pushes the interview toward box-ticking. Consistent
  with the R2 verdict from the first test (relentlessness left SOFT). The
  version-note tail in `artifacts/context.md` from the same review was simply
  cleaned.