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 drives the v2 section.

## 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`.

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

## v2 (larger) — divergence, informed by the first live test

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

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

Proposals (priority order):

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:

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