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.