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.