From 2566d3be5ec73980c6dc65c969d50ff05eb35f46 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sun, 31 May 2026 15:20:06 -0500 Subject: [PATCH] bmad-brainstorming: remove .decision-log.md build-time artifact The workflow-builder writes .decision-log.md to track its own build session; it is a build-time artifact, not part of the shipped skill, so it should not be committed to the project. --- .../bmad-brainstorming/.decision-log.md | 295 ------------------ 1 file changed, 295 deletions(-) delete mode 100644 src/core-skills/bmad-brainstorming/.decision-log.md diff --git a/src/core-skills/bmad-brainstorming/.decision-log.md b/src/core-skills/bmad-brainstorming/.decision-log.md deleted file mode 100644 index f0111670a..000000000 --- a/src/core-skills/bmad-brainstorming/.decision-log.md +++ /dev/null @@ -1,295 +0,0 @@ -# Decision Log — bmad-brainstorming rebuild - -Canonical memory for the rebuild of `bmad-brainstorming` from the legacy numbered-micro-file -architecture into the outcome-driven pattern of bmad-product-brief / bmad-prd / bmad-ux. - -## Session 2026-05-30 - -**Intent:** Edit / rebuild existing skill (in place at `src/core-skills/bmad-brainstorming`). - -**Classification:** Simple Workflow with one quarantine carve-out. Customizable = yes. - -### Load-bearing decisions - -- **Single intent: pure facilitation + continuation.** No create/update/validate split (that pattern fits - document skills; brainstorming is a facilitated session). The skill facilitates a live session and can - resume a prior one. Decided with user. -- **The running log is the memory AND the continuation state.** One terse, append-only session file holds the - goal, the techniques selected, and every idea the user generates/accepts. Kept deliberately lean to minimize - context cost; the final artifacts are produced from it. Borrowed shape from Obra Superpowers' append-only - event log (one entry per line). User: "very succinct as memory, just enough to minimize context." -- **HARD RULE — the LLM never supplies its own ideas in interactive mode.** Its job is to draw ideas out of the - user and push past the obvious. If the user explicitly asks for an idea, give ONE as a one-off, then - immediately return to pushing the user. This inverts a default LLM behavior, so it earns forceful statement - with rationale. User-stated, emphasized. -- **Headless is the ONLY context where the LLM brainstorms on its own.** Given just a topic, headless runs the - techniques itself and produces the artifacts. Because it inverts the central no-own-ideas rule, ALL headless - instructions live in `references/headless.md` and are never loaded in normal mode — quarantined so they can't - bleed into and corrupt the interactive posture. User's explicit requirement. -- **Technique selection: AI-led, others on request.** Facilitator reads the goal and proposes a fitting - technique by default; "browse the library", "surprise me" (random), and "start broad then narrow" - (progressive) are always available but never a forced numbered-menu gate. Builder recommended; user accepted - ("show what you recommend and why"). -- **Finalize → imaginative HTML, no template.** Instruction directs the LLM to be genuinely creative and - whimsical, matched to the spirit of *this* session — sections per technique, creative visualizations, the - summary rendered as it all came together. Explicitly NO template/scaffold (rejected Obra's CSS-class kit). - User: pure per-session creativity. -- **Optional second artifact: succinct brainstorm-intent doc.** User's choice at finalize. Short, sharp, just - the chosen/critical discoveries — clean input for a downstream skill (product-brief, prd) without report - bloat. This is the dual-output distillate pattern. - -- **Synthesis is two-move and is the one interactive moment the LLM adds its own thinking.** First reflect a - sampling of the user's own ideas back (including surprising/random ones from across the session) and let THEM - hunt for conclusions/synergies/themes/what-matters. THEN the LLM leans in creatively to surface the - non-obvious connections the user wouldn't spot right away. The no-own-ideas rule is therefore scoped - explicitly to the *generative* phase so synthesis doesn't collide with it. User refinement. -- **The log is the load-bearing artifact; artifacts are derivations.** "From the decision log we can create any - artifact the user wants for any purpose, with nothing lost." HTML + intent doc are two derivations; others - available on request. (User flagged a future cross-cutting task: retune other skills' `.decision-log.md` to - this same lean append-only standard — NOT part of this build.) - -- **Extensible technique library via customize.toml** (new capability the static-CSV architecture never had). - Two scalars: `favorite_techniques` (names the facilitator proposes first when they fit, AI-led default) and - `additional_techniques` (array-of-tables mirroring the CSV shape `category`/`technique_name`/`description` — - adds whole new techniques AND categories without editing the shipped CSV). Both append-merge so team + user - files each contribute. Wired into SKILL.md `## Choosing Techniques` (proposing/browse/random/progressive all - treat additions as first-class) and into headless.md selection. User idea, added post-build. - -### Borrowed from Obra Superpowers brainstorming skill (researched) - -- **One-question/prompt-per-message** as a hard rule — keeps the human in active generation, operationalizes - "push their creative muscles." -- **Append-only lean log** as continuation memory. -- Rejected: AI-recommends-approaches / convergent-funnel posture, graphviz state machine, CSS HTML kit — all - off-pattern or inject AI ideas. - -### Surviving from legacy version - -- `brain-methods.csv` (technique library) → kept as a swappable asset (`{workflow.brain_methods}`). -- Anti-bias protocol (shift creative domain every ~10 ideas) and quantity goal (100+ collaboratively developed - ideas, stay in generative mode) → kept as facilitation posture, stripped of emoji/MANDATORY/SUCCESS-METRICS - ceremony. - -### Planned file tree - -``` -bmad-brainstorming/ -├── SKILL.md # Overview, Conventions, Activation, facilitation posture, technique flow, running log, finalize -├── customize.toml # output_dir/folder, brain_methods path, activation hooks, persistent_facts -├── references/ -│ └── headless.md # QUARANTINED autonomous mode (the one place the LLM brainstorms itself) -└── assets/ - └── brain-methods.csv # technique library (carried over) -``` - -Legacy files to remove on build: `workflow.md`, `template.md`, `steps/` (8 numbered step files). - -### Adversarial review (3 parallel lenses) + fixes applied - -Ran a Workflow with three review lenses (over-prescription, facilitation-integrity, BMad-conventions) against -the build. Fixes applied: - -- **[HIGH, fixed] Headless detection seam.** The "first message pre-supplies a topic and asks for artifacts" - trigger collided with a normal interactive opening ("brainstorm X and give me the HTML"), risking a present - human flipping the skill into self-generation. Made human-presence the dominant gate in both SKILL.md - activation step 4 and headless.md Detection; dropped the weak payload-shape trigger entirely. -- **[HIGH, fixed] `external_handoffs` declared-but-unused.** Wired it (not deleted) into SKILL.md - `## Producing Artifacts` and headless.md step 5, matching product-brief/prd; headless JSON now populated from - results. Scalar cross-check now 1:1 (every declared scalar referenced, every reference declared). -- **[MEDIUM, fixed] One-off idea exception loose/uncapped.** Tightened trigger to a *direct* ask (not "stuck" - / "what do you think") and capped recurrence (repeated reaching = pivot the technique). -- **[MEDIUM, fixed] Overview forward-reference + Running Log triple-imperative padding.** Trimmed both; added - "never with your own examples" glue at the provocation point and the headless-boundary clause to the scope - statement; ran `on_complete` in headless too. -- **Rejected (reviewers self-assessed as keepers):** ~10-idea rationale, self-contained-HTML constraint, - headless restatement (justified by reference-file self-containment under compaction), and the subjective - "spent / mined out" progression condition (a numeric gate would contradict "resist concluding"). - -### Technique library: 61 → 100, made context-lean via a script (user-requested) - -- **Schema change.** CSV is now `category, technique_name, description, detail`. `description` rewritten to a - terse ≤140-char *gist* that doubles as the index entry AND is enough to run most techniques (the LLM - reconstructs specifics from name + gist — user's insight). `detail` is an optional path (relative to the CSV - dir) to a per-technique instruction file, for techniques complex enough to warrant one — loaded only on - `show`. This absorbs the best of the "sharded files" idea for exactly the cases that need it. No separate - tagline column needed. -- **`scripts/brain.py`** (stdlib-only, PEP723, `uv run`, 15 passing tests in `scripts/tests/`): `categories` / - `list [--category]` / `show ""` (inlines detail file iff present) / `random`. Single source of truth; - index derived; never loads the whole catalog into main context. Decided script over subagent because - selecting/filtering is pure plumbing (quality-bar: scripts do plumbing, prompts do judgment); a subagent - would add latency without saving meaningful context now that the gist index is cheap. Noted one future case a - subagent helps: deep full-description matching across the whole library. -- **Context win:** whole-catalog load was ~4K tokens (61) and would have been ~6.5K at 100; now `categories` - ~0.1K, `list --category` ~0.3-0.6K, `show` ~0.07K each — flat as the library grows. The 100-technique CSV is - 14.6KB, *smaller* than the original 61-technique 16KB because gists replaced the long descriptions. -- **100 techniques, 13 categories** generated via a 13-agent parallel workflow (one flavored generator per - category: shorten existing + invent new), then curated by the parent to exactly 100 (dropped 7 cross-category - near-dups/one exact dup). New categories: `absurdist` (genuinely funny unstickers), `constraint`, - `speculative_future`. Spectrum spans silly→serious per user's "fun wild funny or super helpful." -- **Live detail-file demo:** `Six Thinking Hats` → `assets/techniques/six-thinking-hats.md` (full multi-round - method), proving the lazy-load path end to end. -- **"Invent a technique" option** added to `## Choosing Techniques` (pure prompt; logged as a technique; finalize - may offer to persist a keeper into `additional_techniques`). SKILL.md technique section + headless both rewired - to reach the library only through the script. Scalar consistency re-verified identical; scan-scripts passes. - -### Interactive tool techniques — a technique can BE a generated interactive HTML app (user breakthrough) - -The detail-file mechanism generalized into a new class: a technique whose "instructions" tell the LLM to -generate a bespoke, self-contained **interactive HTML tool** (CDN libs like three.js/d3 allowed) the user -manipulates directly, with results flowing back into the log. - -- **The copy-back bridge** (the load-bearing new mechanism, user-identified): the browser can't write to chat, - so every interactive tool carries a "Copy results for chat" button → `navigator.clipboard.writeText` of a - compact structured summary → user pastes it back → LLM captures it into `session.md` under that technique → - next technique. Stated ONCE in `references/interactive-tools.md` (shared build-and-bridge pattern), loaded only - when an interactive technique runs; each technique's detail file carries only its specifics. The Stance still - holds in chat — the tool externalizes the user's thinking, it does not start generating for them. Graceful - fallback to conversational facilitation if HTML can't run. -- **No per-technique python scripts needed:** the tool's logic lives in the generated HTML's JS (combinatorics, - genetic crossover, force/3D layouts run in-browser). `brain.py` stays the only script. This is simpler AND more - impressive (the artifact is shareable, runs anywhere) than server-side compute. -- **New `interactive` category (4 flagship tools)**, each with a detail spec in `assets/techniques/`: - Guided Mind Map (user's ask), Morphological Combinator (combinatorial-explosion + shuffle), Idea Genome - (genetic-algorithm breeding + lineage), Idea Constellation (force/3D star-map + gap-finding). Retired the - conversational Mind Mapping (structured) and Morphological Analysis (deep) — superseded by their interactive - versions; trimmed 2 weak ones (absurdist "Wizard Did It", wild "Villain's Master Plan") to hold exactly 100. -- **Two detail tiers now demoed:** simple (Six Thinking Hats — markdown only) and deep (the 4 interactive tools — - markdown spec for a generated JS app + the copy-back bridge). SKILL.md `## Choosing Techniques` routes to - `references/interactive-tools.md` + `show` when an interactive technique runs. scan-scripts passes; SKILL.md 92 - lines. Cruft (`.pytest_cache`, `__pycache__`) removed from the tree. - -### Open item for BMad (not a build defect) - -`.decision-log.md` trips the path-standards scanner (it flags any non-SKILL root `.md`). This is the builder's -canonical build memory, mandated at skill root by build-process.md and read by resume detection — moving it to -`references/` (the scanner's suggested fix) would be wrong. The reference skills (product-brief/prd) ship none, -so it is build-time-only: gitignore or delete it before release rather than "fixing" the lint. - -### Interactive tools: bundled & tested, not generated per-run (user-directed pivot) - -User flagged the live-generation approach as needlessly risky (the constellation demo shipped two engine-layer -typos that blanked the page) and conceptually wrong for one tool. Two decisions: - -- **Bundle the flagship interactive tools as tested HTML shells; inject data, never regenerate code.** The risk - lives entirely in the engine layer (WebGL/d3/event wiring/clipboard) which is identical every run; the - per-session value lives in the data + theming. So each tool now ships as a self-contained - `assets/techniques/.html` with a `