method-brainstorm skill
✓ VerifiedExplores research ideas, compares study designs, and defines requirements to create a protocol or analysis brief for future planning.
- GitHub stars
- 6
- Files
- 13
- Last commit
- Oct 31, 2026
- License
- MIT
- Allowed tools
- —
What does the method-brainstorm skill do?
method-brainstorm explores research ideas, compares study designs, and defines requirements to create a protocol or analysis brief for future planning.
Summary generated from the skill's SKILL.md.
About the method-brainstorm skill
Refining vague research ideas into structured study protocols is the primary function of this skill. It serves researchers and data scientists who need to weigh different study designs, define populations, and establish success criteria before any analysis code is written. By acting as a thinking partner, the tool helps users explore what to study rather than how to implement it, preventing common errors like accidental population or endpoint decisions during the coding phase.
An agent should load this skill when a user presents a research question or a hypothesis that requires scoping. The process involves a collaborative dialogue where the agent asks one decision-changing question at a time, using numbered choices or single-select menus to guide the user. The final output is a durable requirements document, such as a study protocol or analysis brief, saved as a markdown or HTML file in the docs/brainstorms/ directory. This document provides the necessary context for the method-plan skill to execute the actual analysis.
What an agent can do with it
- 1Generate a formal analysis briefUsers can produce a structured requirements document that serves as the foundation for subsequent technical planning.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the method-brainstorm skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the method-brainstorm skill in Plugin
/plugin marketplace add sajor2000/methodsmith /plugin install methodsmith@methodsmith
Install the method-brainstorm skill in Claude Code
~/.claude/skills/method-brainstorm/SKILL.md
$ npx degit sajor2000/methodsmith/plugins/methodsmith/skills/method-brainstorm ~/.claude/skills/method-brainstormInstall the method-brainstorm skill in Claude Code (project)
.claude/skills/method-brainstorm/SKILL.md
$ npx degit sajor2000/methodsmith/plugins/methodsmith/skills/method-brainstorm .claude/skills/method-brainstormInstall the method-brainstorm skill in Codex
~/.agents/skills/method-brainstorm/SKILL.md
$ npx degit sajor2000/methodsmith/plugins/methodsmith/skills/method-brainstorm ~/.agents/skills/method-brainstormInstall the method-brainstorm skill in Gemini CLI
~/.gemini/skills/method-brainstorm/SKILL.md
$ npx degit sajor2000/methodsmith/plugins/methodsmith/skills/method-brainstorm ~/.gemini/skills/method-brainstormInstall the method-brainstorm skill in Claude.ai
npx degit sajor2000/methodsmith/plugins/methodsmith/skills/method-brainstorm method-brainstorm && zip -r method-brainstorm.zip method-brainstorm # claude.ai → Customize → Skills → + → Create skill → Upload a skill → method-brainstorm.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablesajor2000/methodsmith/plugins/methodsmith/skills/method-brainstorm is public and reachablegithub.com/sajor2000/methodsmith/tree/HEAD/plugins/methodsmi ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-31github.com/sajor2000/methodsmith/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/sajor2000/methodsmith/blob/HEAD/plugins/methodsmi ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/sajor2000/methodsmith/blob/HEAD/plugins/methodsmi ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 171 linesgithub.com/sajor2000/methodsmith/blob/HEAD/plugins/methodsmi ↗Pass
SKILL.md
View on GitHubBrainstorm a Research Question or Study
Skill Value
- Problem it solves: Vague study ideas can turn into SAPs or code that silently invent population, endpoint, comparison, or feasibility decisions.
- Use when: The user wants to brainstorm, refine a research question, compare study designs, or decide what evidence would be worth generating.
- Output: A requirements, protocol, or analysis brief under docs/brainstorms/ that method-plan can use as origin context.
- Ask only if: Only for study-shaping decisions that are not clear from the prompt, repo, prior artifacts, or source documents.
- Do not do: Do not write the SAP, implement analysis code, or force a long brainstorm when the request is already well scoped.
- Interaction: Check repo/config/chat evidence first. Ask one decision-changing question at a time; use the current harness's blocking question UI when available, otherwise present numbered choices and wait.
Resolve the current year at runtime (date +%Y) when dating requirements documents.
Brainstorming answers WHAT to study; method-plan answers HOW to execute the analysis. The durable output is a requirements document (a study protocol or analysis brief elsewhere), strong enough that planning need not invent study design, scope boundaries, or success criteria/endpoints. This skill does not implement analysis code.
IMPORTANT: All file references in generated documents must use repo-relative paths (e.g., src/models/user.rb), never absolute paths.
Core Principles
- Assess scope first - Match ceremony to the size and ambiguity of the work.
- Be a thinking partner - Suggest alternatives, challenge assumptions, and explore what-ifs instead of only extracting requirements.
- Resolve study design decisions here - Research questions, populations, exposures, outcomes, scope boundaries, and success criteria/endpoints belong here; detailed analysis implementation belongs in planning.
- Keep implementation out of the requirements doc by default - No specific packages, SQL, model specifications, file layouts, or code-level design unless the brainstorm is itself about a methodological or analytical architecture decision.
- Right-size the artifact - Simple work gets a compact document or brief alignment; larger work gets a fuller document.
- Apply YAGNI to carrying cost, not coding effort - Prefer the simplest design that delivers meaningful evidence; include low-cost analytical rigor when its ongoing cost is small.
Interaction Rules
These apply to every brainstorm, including the universal flow in references/universal-brainstorming.md.
- Ask one question at a time - One question per turn, even when sub-questions feel related.
- Prefer single-select multiple choice - For one direction, priority, or next step.
- Use multi-select rarely and intentionally - Only for compatible sets (goals, constraints, non-goals, success criteria); if priority matters, follow up on which is primary.
- Use the Skill Value interaction rule - Ask only decision-changing questions after checking evidence. Use the harness's blocking question UI when available; otherwise present numbered choices and wait.
- Use prose only when the question is genuinely open - Drop the blocking tool only when (a) the answer is inherently narrative, (b) the question is diagnostic or introspective and options would leak priors and bias the answer, or (c) 3-4 genuinely distinct, plausible options cannot be written without padding or strawmen. Rule 1 still applies.
Keep outputs concise: short sections, brief bullets, only enough detail for the next decision.
Research Question Description
<research_description> #$ARGUMENTS </research_description>
If the research description above is empty, ask the user: "What would you like to explore? Please describe the research question, hypothesis, or study idea you're thinking about." Do not proceed without one.
Execution Flow
Phase 0: Resume, Assess, and Route
0.0 Resolve Output Mode
Resolve OUTPUT_FORMAT before any other phase. Output is exclusive: markdown (.md) OR HTML (.html), never both.
Read config. The repository root is pre-resolved at skill load:
!git rev-parse --show-toplevel 2>/dev/null || true
If that line is an absolute path, use it as <repo-root>; if empty or a literal command string, run git rev-parse --show-toplevel at runtime. Read <repo-root>/.methodsmith/config.local.yaml with the native file-read tool. In a linked worktree without the file, resolve the absolute common Git directory and try the main checkout's copy. If none is found, use defaults.
Precedence:
- CLI arg. A token with the literal prefix
output:is stripped from the research description; match its value case-insensitively tomdorhtml. Bareoutput:falls through. An unknown value (e.g.,output:pdf) falls through and, above the post-generation menu, emits:Ignored unknown output: value '<value>' -- using <resolved_format> instead. - Config. An active, non-commented
brainstorm_output:ofmdorhtml; anything else falls through silently. - Default.
OUTPUT_FORMAT=md. - Pipeline override. From LFG or any
disable-model-invocationcontext, forcemdregardless of 1-3.
Only literal-prefix flag tokens (output:, mode:, delegate: where applicable) are stripped; other <word>:<word> tokens pass through.
Read references/markdown-rendering.md when md, or references/html-rendering.md plus references/html-visuals.md when html; both pair with references/brainstorm-sections.md (same content, different presentation). The choice does not propagate to method-plan, which resolves its own plan_output.
0.1 Resume Existing Work When Appropriate
If the user references an existing brainstorm, or an obvious recent matching *-requirements.{md,html} exists in docs/brainstorms/: read it and confirm: "Found an existing requirements doc for [topic]. Should I continue from this, or start fresh?" When resuming, summarize its state, continue from its decisions and open questions, and update it instead of duplicating. Write back in the existing file's format unless output: overrides; pipeline mode still forces markdown, writing a parallel .md and leaving any .html untouched.
0.1b Classify Task Domain
Ask: does the task involve designing, analyzing, or architecting a research study or data analysis? (not merely mentioning data or research).
- Data science / study design -> continue to 0.2: research questions, hypotheses, datasets, populations, exposures, outcomes, statistical analyses, or designing/executing/interpreting a study.
- Non-study brainstorming -> none of those signals AND the user wants to explore, decide, or think through something in another domain. Read
references/universal-brainstorming.md, follow it, and skip Phases 0.2-4. Core Principles and Interaction Rules still apply. - Neither -> quick help, error message, factual question, or single-step task: respond directly with no brainstorm.
0.2 Assess Whether Brainstorming Is Needed
Requirements are clear when the user gives specific success criteria or endpoints, references a design or prior analysis to follow, describes exact outcomes and populations, and scopes tightly. Then keep it brief: confirm understanding and offer concise next steps; write a short requirements document only when a durable handoff is valuable. Skip Phases 1.1 and 1.2; go to 1.3 or 2.9.
0.3 Assess Scope
Classify from the description plus a light repo scan:
- Lightweight - small, bounded, low ambiguity (descriptive analysis, single-table query)
- Standard - normal study or bounded analysis with some design decisions
- Deep - cross-cutting, multi-dataset, strategic, or highly ambiguous
If unclear, ask one targeted question. For Deep, also pick a sub-mode:
- Deep — analysis (default): an existing program anchors investigators, core question, prior work, and workflows; the brainstorm refines within it.
- Deep — program: investigators, core questions, literature positioning, or primary workflows are materially unresolved. Existing analyses lower the odds but do not rule it out. Program tier adds Phase 1.2 questions and requirements sections.
Phase 1: Understand the Idea
1.1 Existing Context Scan
- Lightweight: search for the topic, check whether something similar exists, move on.
- Standard and Deep: Constraint check — read
AGENTS.md(andCLAUDE.mdonly as compatibility context) for workflow or scope constraints. Topic scan — search relevant terms, read the most relevant existing artifact (brainstorm, plan, spec, prior analysis, protocol), and skim adjacent examples.
If nothing obvious appears, say so and continue.
- Verify before claiming — When the brainstorm touches checkable infrastructure (tables, datasets, config, dependencies, variable definitions), read the sources. Verify every claim that something is absent; otherwise label it an unverified assumption.
- Defer analysis decisions to planning — Statistical methods, query optimization, notebook structure, and pipeline architecture belong in planning unless the brainstorm is about that decision.
Slack context (opt-in, Standard and Deep; never auto-dispatch):
- Tools available + user asked: dispatch
method-slack-researcherwith a topic summary alongside 1.1 and fold findings into context. - Tools available + not asked: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt."
- No tools + asked: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search."
1.2 Study Design Pressure Test
Before generating approaches, scan the opening for rigor gaps (internal analysis; raise only gaps that exist, during 1.3).
- Lightweight: Is this a real clinical or scientific question? Does an existing analysis already cover it? Is there a clearly better framing at near-zero cost?
- Standard and Deep: read
references/study-design-pressure-test.mdfor the gap lenses, domain probes, R-specific probes, synthesis questions, Deep/program additions, and probe wording.
1.3 Collaborative Dialogue
Follow the Interaction Rules.
- Ask what the user is already thinking before offering ideas.
- Start broad (question, population, clinical significance), then narrow (inclusion/exclusion, confounders, edge cases).
- Rigor probes fire before Phase 2 and are prose, not menus (Rule 5(b)). Each scope-appropriate gap found in 1.2 gets its own direct prose probe; one probe satisfies one gap. Interleave with narrowing, but Phase 1 cannot end with an un-probed gap. When the design appropriateness gap is present, its probe is the final one before Phase 2. Record genuine uncertainty as an explicit assumption rather than skipping the probe.
- Clarify the problem frame, validate assumptions, and ask about success criteria/endpoints.
- Make requirements concrete enough that planning will not invent study design decisions.
- Surface dependencies (IRB, data access, sample size) only when they materially affect scope.
- Bring ideas, alternatives, and challenges instead of only interviewing.
Exit condition: the idea is clear OR the user explicitly wants to proceed.
Phase 2: Explore Study Design Approaches
If multiple plausible directions remain, propose 2-3 concrete study design approaches from the literature and conversation; otherwise state the recommended direction directly. Before presenting them, read references/evidence-access.md and run its literature pulse per option (Look up here: prior studies per design option, hit count and 2-3 PMIDs, labelled abstract, never a systematic search).
Run this comparison only when at least two options are genuinely viable and the choice could materially affect scientific value, feasibility, or interpretability. Do not add agent fan-out for routine clarification; generate the alternatives in the normal collaborative flow.
- Make alternatives meaningfully different: design (RCT vs. observational vs. quasi-experimental), analysis strategy (regression vs. matching vs. time-series), population or data source (single- vs. multi-center; EHR vs. claims vs. registry), or outcome definition/timeframe.
- Use at least one non-obvious angle: inversion (study the inverse outcome), constraint removal (a linked dataset), or analogy from another clinical domain.
- Include one adversarial or assumption-inverting challenger when a meaningful one exists. Flag any attractive-but-unsuitable option as a trap with its concrete reason (infeasible data access, invalid comparison, unmanageable confounding, disproportionate carrying cost). Do not manufacture a trap when every viable option is reasonable.
- When useful, add one higher-upside challenger (the adjacent addition that most raises rigor, compounding evidence, or clinical relevance without disproportionate cost), never as the default; omit it when the study is already over-scoped.
- At program tier, alternatives differ on what is studied (question, population, exposure), not how the analysis runs.
For each approach: 2-3 sentence description, pros and cons, key risks or unknowns (data availability, bias, confounding), and when it fits best. Present all approaches before recommending, then recommend with reasons: prefer simpler designs when complexity carries real cost, but keep low-cost, high-value rigor. If one approach is clearly best, skip the menu and recommend directly. When relevant, say whether the choice replicates an existing design, extends an existing analysis, or is net new.
Phase 2.9: Synthesis Checkpoint
Before writing the requirements document, present and confirm the scope synthesis. Read references/synthesis-summary.md and references/synthesis-discipline.md for the contract; it is the scope checkpoint doc-write consumes, not a draft of the doc.
Phase 3: Capture the Requirements
Write or update a requirements document only when the conversation produced durable decisions. Read references/brainstorm-sections.md for the section contract, use the Phase 0.0 rendering reference for presentation, and use references/requirements-capture.md for the health data science template and completeness checks. When a diagram or comparison table would make the requirements much easier to grasp (multi-step study flow, 3+ interacting populations or exposures, competing designs), read references/visual-communication.md.
For Lightweight work keep the document compact, or skip it when only brief alignment is needed.
Phase 4: Handoff
Present next-step options and execute the user's selection. Read references/handoff.md for the option logic, dispatch instructions, and closing summary format.
Files in this skill
13method-brainstorm skill questions
How do I install the method-brainstorm skill in Claude Code?
Run npx degit sajor2000/methodsmith/plugins/methodsmith/skills/method-brainstorm ~/.claude/skills/method-brainstorm. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the method-brainstorm skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What is the difference between method-brainstorm and method-plan?
Brainstorming answers WHAT to study, while planning answers HOW to execute the analysis.
What kind of output does the skill produce?
It produces a requirements document, such as a study protocol or analysis brief, saved in markdown or HTML format.