brainstorming

Brainstorming

Turn an idea into a captured brainstorm — a single markdown file under work/<initiative>/brainstorm.md that preserves the why behind every decision so the next session can resume without re-deriving anything.

When you're done

brainstorm.md exists, the user has approved the contents, and you've offered to invoke assessing-brainstorms to graduate it to a spec or roadmap. Do not write code. Do not draft a spec. Do not invoke any other skill.

Where it lives

• Project-internal initiative → <project>/work/<initiative>/brainstorm.md
• Cross-project initiative → /home/sonderbread/websites/work/<initiative>/brainstorm.md

<initiative> is a kebab-case slug. Run dev-pipeline.js init from the appropriate project root to scaffold the folder, the templated brainstorm.md, and the gitignore entry in one shot — see the next section.

Process

1. Orient with targeted reads. Use the most stable reference available — symbol > flag > line range — not bulk file reads:
   • get_project_overview <project> for high-level shape.
   • find_identifier <name> to locate a symbol before reading anything.
   • get_node_bundle <project> <file> <name> to read a single function with its edges and labels. The symbol name is the stable handle — the equivalent of a flag for source code. Survives line-shifts.
   • grep_project <project> <pattern> for textual contracts (READMEs, slash commands, docs that aren't in the code graph).
   • For prereq brainstorms or related docs from the related: frontmatter list, reference by section number (§2) or flag (<!-- decision:3 -->). Never load the whole file.
   • Read <path> offset=N limit=M is the fallback when no symbol or flag exists (config files, raw text, file headers). Don't ask questions whose answers are visible in the graph.
2. Decompose if necessary. If the request describes multiple independent subsystems, name that explicitly. Help the user pick which sub-initiative gets brainstormed first; the rest become a flat list at the bottom of the brainstorm.
3. Ask one question at a time. Multiple choice when possible. Cover purpose, constraints, success criteria, what's already been ruled out.
4. Propose 2–3 approaches with tradeoffs. Lead with your recommendation and the reason. Counter-propose from knowledge — if the user is reaching for a path that has known drawbacks you can name, surface them before drafting.
5. Draft the brainstorm sections one at a time. Show each section, get approval, move on. Sections scaled to complexity.
6. Populate the scaffolded brainstorm.md that dev-pipeline.js init wrote. Use the structure below as the section reference. Do not commit.
7. Self-review. Look at the file once with fresh eyes. Fix placeholders, contradictions, ambiguity inline. No re-review pass.
8. Hand off. Tell the user the file path and offer: "Ready to assess this into a spec or roadmap when you are — invoke assessing-brainstorms." Do not invoke it yourself.

Brainstorm file structure

You MUST scaffold the brainstorm via dev-pipeline.js init. Do not hand-write the structure from memory; do not adapt a prior brainstorm. Init copies the canonical template into the new initiative folder, writes brainstorm.tracker.json, and appends work/ to .gitignore if missing. The template is the single source of truth for section ordering, frontmatter shape, and required content — straying from it breaks downstream tooling (assessing-brainstorms reads §2 by position, dispatching-chunks reads frontmatter prereqs/related).

node greymatter/scripts/dev-pipeline.js init <initiative>

Run from the project root (project-internal) or from /home/sonderbread/websites/ (cross-project). Then populate the scaffolded work/<initiative>/brainstorm.md. The template carries the required sections (Origin, Decisions, Open threads, Verbatim phrasings, Next steps, Resumption checklist) with placeholder content marked <TODO>. You MAY add topic-shaped sections between §2 and the open-threads section as the conversation warrants. You MUST NOT remove or reorder the required sections.

Anti-patterns

• Skipping decomposition. "Build me a platform with chat, billing, and analytics" is three brainstorms, not one. Name the split before drafting.
• Burying the why. Decisions without rationale strand the next session. Every settled decision in §2 gets a Notes column entry.
• Implementation creep. This skill ends at a markdown file. Anything code-shaped is a different phase.
• Re-deriving instead of resuming. If a prior brainstorm covers prereqs, link to it in frontmatter and reference it; don't restate.