brainstorm-artifact

name

brainstorm-artifact

description

Generate an interactive React-based brainstorming wizard artifact for scoping MVPs, feature sets, project requirements, or client discovery. Use this skill whenever the user wants to brainstorm features, scope an MVP, lock decisions on a project, gather client requirements, define what's in or out of scope for a build, or capture structured feedback from a stakeholder. Trigger this even when the user uses casual phrasing like "let's figure out what to build", "I need to scope this", "help me think through features", "I'm confused on what we want", or "send this to my client to fill out". Two output modes are supported, an internal mode with gamification and live wizard flow for solo or team scoping sessions, and a client mode with a clean fillable form that exports to JSON or PDF for stakeholders to return. The skill adapts its theme to match the project's domain (game dev, military/government, research/editorial, or a custom theme defined per project) so each artifact feels native to its project rather than generic.

Brainstorm Artifact Skill

CRITICAL ENFORCEMENT RULES -- READ BEFORE ANY OTHER SECTION

These rules are non-negotiable. Every brainstorm artifact produced by this skill must satisfy all of them, every time, with no exceptions.

RULE 1: Use the template. Never improvise the rendering code. The file templates/wizard.jsx contains the canonical rendering code for this artifact. You MUST read it before generating any artifact. You copy that rendering code verbatim and only change BRAINSTORM_DATA. You do NOT write new rendering code from scratch. You do NOT add new components that are not already in the template. You do NOT improvise a "simpler" version. If the template is unavailable for any reason, say so and stop rather than generating a custom artifact.

RULE 2: Output a .jsx file artifact, not inline chat content. The artifact is always a React .jsx artifact rendered in the Claude interface. It is NEVER a list of bullet points, NEVER inline markdown, NEVER a plain HTML page unless explicitly asked for the client_form.html variant. The wizard lives in the artifact panel, not in the chat.

RULE 3: Apply the correct theme. Never invent a palette from scratch. Select themeKey from the three shipping themes (vetassist_tactical, game_dev_arcade, research_editorial) or add a new theme to the THEMES constant following the pattern in references/themes.md. You do NOT invent bright, saturated, or "loud" palettes that are not grounded in one of these theme families. Default theme calibration: dark background, muted accents, two anchor colors maximum in any one view. The game_dev_arcade theme is the loudest permitted palette and is only used for game development work.

RULE 4: Every question carries all four affordances. Free-text override, voice input, hybrid composer, and feedback flag must appear on every question, every time. They are mandatory. You do NOT simplify questions to just pill buttons without the affordance bar below them.

RULE 5: No em-dashes anywhere in the artifact. Not in question text, rationale text, labels, comments, or UI copy. Use commas, colons, or parentheses instead.

RULE 6: All values are config-driven. Colors, labels, rank names, achievement text, XP thresholds, and question content all come from BRAINSTORM_DATA and THEMES. Nothing is hardcoded inline in JSX.

WHAT INCONSISTENT OUTPUT LOOKS LIKE -- RECOGNIZE AND AVOID:

• Bright neon colors on a non-game-dev artifact (RULE 3 violation)
• Questions displayed as plain text with a text area and no pills (RULE 1 violation, template not used)
• Wizard content appearing in chat as bullet points instead of a rendered artifact (RULE 2 violation)
• Questions missing the affordance bar (RULE 4 violation)
• "I'll create a simple version for now..." -- this is always wrong, use the template

---

This skill produces an interactive brainstorming artifact that captures structured decisions about a project's scope, features, or MVP. The artifact has two modes that share a single schema, an internal mode for working sessions and a client mode for sending to stakeholders. The shared schema means a client's returned answers slot directly into your internal scoping artifact without translation.

Why this skill exists

When scoping a project, decisions tend to get lost in chat. A brainstorm artifact does three things that chat does not. It captures the answer in a structured, reusable form. It enforces the user actively answers each scoping question rather than letting ambiguity ride. It produces an exportable record that survives the session.

The skill is configuration-driven, which means new themes, new question types, and new affordances are added by extending data structures rather than by modifying the rendering code. This matches Marcus's coding standards (see references/coding_standards.md) and keeps the artifact maintainable as the project library grows.

When to use this skill

Trigger this skill whenever any of these are true:

• The user wants to brainstorm features, scope an MVP, or lock decisions on a project
• The user is unsure what features the next iteration should include and needs structured help thinking through it
• The user mentions sending a discovery document or scoping questionnaire to a client
• The user references a previous brainstorm artifact and wants to build on it
• The user is starting a new project and needs to capture initial requirements
• The user mentions one of these projects by name: VetAssist, Agent Forge, or any new project where scoping is needed

Do not trigger this skill for:

• Quick one-off questions that have a single answer and don't need a structured wizard
• Pure technical implementation questions with no scoping decisions involved
• Casual conversation where the user is thinking out loud and explicitly does not want a structured artifact

Two modes, one schema

Internal mode

A live wizard with gamification (XP, ranks, achievements, optional sound), all six question types, all four affordances per question (free-text override, voice input, hybrid composer, feedback flag), and a section-by-section progression. Used during solo or team scoping sessions. Output is a locked-decisions JSON object that becomes the source of truth for the project's scope.

Client mode

The same question engine, but with gamification stripped out and the UI simplified to a clean form. Voice input stays (clients appreciate it). The free-text and feedback affordances stay (clients need escape hatches). Two export options at the bottom: download answers as JSON (for you to ingest) or download answers as a filled PDF (for the client's records). No Claude required on the client's end. The HTML file is fully self-contained and works offline once opened.

Input schema (BRAINSTORM_DATA)

Every brainstorm artifact has a single configuration object near the top of the React component called BRAINSTORM_DATA. The skill produces a new artifact by populating this object and leaving the rendering code unchanged. The object looks like this:

const BRAINSTORM_DATA = {
  metadata: {
    projectName: "VetAssist",
    sessionDate: "2026-05-01",
    themeKey: "vetassist_tactical",   // selects from THEMES constant
    mode: "internal",                  // "internal" or "client"
    preLockedContext: [
      { label: "Platform", value: "Web-first PWA" },
      { label: "Tech stack", value: "Next.js + Postgres" }
    ]
  },
  sections: [
    {
      id: "platform_decisions",
      title: "Platform & Storage",
      questions: [
        {
          id: "draft_storage",
          type: "single",
          prompt: "Where do in-progress drafts live during the wizard session?",
          options: [
            { label: "Local-first (IndexedDB)", rationale: "Works offline; sync on save." },
            { label: "Cloud-first (Postgres)", rationale: "Multi-device; requires connection." },
            { label: "Hybrid", rationale: "Local cache + explicit cloud sync." },
            { label: "Session-only", rationale: "No persistence; fastest path." }
          ]
        }
      ]
    }
  ]
};

The six supported type values are single, multi, true_false, ranked, numeric_scale, and abc_match. See references/question_types.md for the full schema of each type.

Theme system

Three shipping themes, plus a documented pattern for adding project-specific themes. Themes are loaded from a THEMES constant in the artifact and selected via metadata.themeKey. Each theme is a complete token package (palette, font pairing, rank names, icon character) so themes never cross-pollinate.

Default theme suggestions by project type:

• VetAssist or government/compliance work → vetassist_tactical (dark forest greens, Playfair Display + JetBrains Mono, Navy ranks)
• Agent Forge or game dev work → game_dev_arcade (deep purples and hot pink, Press Start 2P + JetBrains Mono, game dev ranks)
• Research, writing, regulatory analysis → research_editorial (parchment cream and brown, Playfair Display + Georgia, academic ranks)

When none of these fit, add a new theme to the THEMES constant. Adding a theme is a pure addition, not a modification to existing themes. See references/themes.md for the full theme token list and instructions for defining a new one. Marcus's preference is themes that fit the project's domain naturally without being overpowering, so favor restrained accent colors and one display font paired with a readable body font over loud palettes.

Question types (six)

Brief overview here. Full schema and examples in references/question_types.md.

• single — pick one option from a stack of pills. Use for binary or n-ary architectural choices where only one path can be taken.
• multi — pick any subset (zero or more) from pills. Use when compatible options can be combined.
• true_false — special case of single with two side-by-side pills labeled True/False or Yes/No. Use for clean binary decisions.
• ranked — reorder options into priority sequence with up/down arrows. Use for hierarchy decisions like "rank features by what would be cut last".
• numeric_scale — grid where each row is a subject and each column is a numeric scale value. Use for rating multiple subjects on the same dimension.
• abc_match — grid where each row maps to a category column. Use for assigning many items to a smaller number of categories (tier allocation, MoSCoW prioritization).

If a question doesn't fit cleanly, restructure the question or add a seventh type to the schema. Do not force a question into the wrong type, the user will produce bad answers and the locked decisions corrupt downstream.

Four affordances on every question

Every question carries four affordances regardless of type. These are escape hatches for when the question itself is wrong or incomplete, which is inevitable when scoping novel work.

• Free-text override — multi-line text area for an answer in the user's own words. Does not delete preset selections, captures additional context.
• Voice input — uses the browser's Web Speech API (no external service, no API key, works offline). Appends transcript to free-text override. Hides the button if the browser doesn't support the API rather than showing an error.
• Hybrid composer — smaller text area for combining a preset selection with custom qualifications. Distinct from override in that it supplements rather than replaces the preset answer.
• Feedback flag — text area for flagging the question itself as ambiguous, missing options, or poorly worded. Captured in export with a FEEDBACK FLAG: prefix so the next brainstorm iteration can address it.

In client mode, all four affordances stay. Clients especially benefit from voice and feedback flag.

Gamification layer (internal mode only)

Optional, governed by a single toggle that defaults on for the artifact author. When off, the artifact reverts to a clean baseline.

• XP and ranks — actions award XP. Selections give 10 XP, override/hybrid/flag give 5 XP, achievements give their listed value. Rank threshold is configurable (default 200 XP per rank). Rank names come from the active theme.
• Achievements — seven shipping achievements (First Decision Locked, Voice Recon, Field Notes, After Action Review, Section Cleared, Tier Master, Field Manual Complete). Add new achievements by appending to the catalog, not by modifying existing ones.
• Sound cues — Web Audio API generates short tones (selection, lock, achievement unlock, rank up). No external assets. Separate toggle from gamification visibility, so users can have visible XP without sound.

The pattern is event-driven. Actions emit into a custom event bus, subscribers handle XP, achievements, and sound. New gamification features are new subscribers, not modifications to action emission. See references/gamification.md for the event names and the achievement catalog.

In client mode, gamification is disabled and hidden entirely. Clients should not see XP bars or hear sound cues. Their job is to answer questions, not earn ranks.

Output formats

Internal mode export

A JSON object with the full schema preserved, plus the user's answers, plus any free-text/hybrid/flag content, plus session metadata (start time, end time, sections completed, total XP if gamification was on). This is the locked-decisions document.

Client mode export

Two buttons at the bottom of the form. The first downloads the same JSON object the client filled in. The second renders the answers into a filled PDF using the browser's built-in print-to-PDF (no external library needed, works offline). The PDF is a human-readable record the client keeps for themselves. The JSON is what they email back to you.

Generating a new brainstorm artifact

When the user asks for a new brainstorm, follow these steps in order. Do not skip steps.

1. Read templates/wizard.jsx first. Before writing a single line of output, call the view tool on templates/wizard.jsx. This is mandatory. The template is the output. You are not writing new code, you are populating a schema.

2. Read references/themes.md. Confirm which shipping theme applies. If none fit, define the new theme in the THEMES constant using the token pattern from that file before touching anything else.

3. Ask which mode if not obvious from context. Internal for working sessions, client for sending to stakeholders.

4. Capture metadata -- project name, session date, any pre-locked context from prior sessions or known constraints.

5. Draft sections and questions -- read references/question_types.md to pick the right type for each decision. Restructure questions that do not fit a type, do not force a wrong type.

6. Generate the artifact by copying templates/wizard.jsx verbatim, then replacing only BRAINSTORM_DATA with the new content and setting themeKey in the metadata. The rendering code (components, hooks, gamification logic, affordance bar) stays unchanged. Create it as a .jsx artifact in the chat.

7. For client mode, generate a standalone HTML version from templates/client_form.html with the same BRAINSTORM_DATA inlined. The HTML file is what gets emailed to the client.

Shortcut that is always wrong: Generating a minimal custom React component with just text areas and buttons because it seems simpler. The template exists precisely because simpler components do not deliver the wizard experience Marcus needs.

Building on prior brainstorms

If the user references a prior brainstorm, ask them to paste the JSON export or attach the file. Read it, use it as metadata.preLockedContext in the new artifact (locked decisions from the prior session become facts the new session builds on). This is how brainstorms compound rather than restart from zero each time.

Memory and persistence

The artifact persists answers locally in the browser using window.storage (in Claude artifacts) or localStorage (in standalone HTML, only for the client form). The user can close and reopen without losing progress. On final submit, the JSON export is the durable record, the in-browser storage is a working draft.

Key references

• references/question_types.md — full schema and rendering rules for all six question types
• references/themes.md — theme token list and pattern for adding project-specific themes
• references/gamification.md — event bus, XP rules, achievement catalog
• references/coding_standards.md — Marcus's coding standards applied to this skill (event-driven, configuration-driven, no hardcoded values)
• templates/wizard.jsx — the React wizard template, internal mode
• templates/client_form.html — the standalone HTML template, client mode
• examples/vetassist_round_two.jsx — canonical sample showing every feature

A note on Marcus's preferences

Marcus prefers UI that's distinctive but not overpowering. Themes should feel native to the project, not generic. Code should use variables not hardcoded values. Architecture should be event-driven and configuration-driven so future expansion is additive. Long-form text in this skill avoids em-dashes per Marcus's user preference.

When generating an artifact, default to restrained palette intensity. The vetassist_tactical theme is a good calibration point, dark and serious without being grim. The game_dev_arcade theme is the loudest of the three, use it only when the project is genuinely game-dev focused. The research_editorial theme is the most subdued, use it for any text-heavy or analytical work.