---
name: brainstorming
description: "Use before implementing a feature, a change in behavior, or a bug fix — however small. Not for questions, checks, or edits that change no behavior (typos, documentation or configuration only, mechanical refactors)."
title: brainstorming
canonical_url: https://skilld.dev/gh/jetbrains/thinkrail/brainstorming
last_updated: 2026-10-26T00:28:19.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [amending-specs.md](https://skilld.dev/api/skills-raw/jetbrains/thinkrail/brainstorming/amending-specs.md), [fixing-a-bug.md](https://skilld.dev/api/skills-raw/jetbrains/thinkrail/brainstorming/fixing-a-bug.md).
>
> If the user asked to install this Skill, run `npx skilld install jetbrains/thinkrail/brainstorming`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/brainstorming`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jetbrains/thinkrail/brainstorming) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/brainstorming`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/brainstorming --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/brainstorming --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Brainstorming

## Interview before you build

- Every feature, behavior change, or bug fix goes through this workflow. Depth scales with the
  change and never drops to zero: a small change gets one short round and a few lines of task-spec.
- The aim is a design the user understands and has accepted, recorded in a spec-graph `task-spec`,
  built, and then reflected in the durable specs — not a speculative implementation.
- Do not implement until the design is accepted. An explicit design or acceptance criteria in the
  request count as approval of what they cover; build on them and never re-ask them.

## Doc map

- `fixing-a-bug.md` — the bug branch (step 4).
- `amending-specs.md` — bringing the durable specs in line with what was built (step 9); the tail of
  both paths and where this workflow ends.

## The workflow

1. **Orient.** Use the spec-graph skill to find the specs that govern the area; read code second to
   confirm implementation details. Do not read unrelated specs. Note any non-obvious decision the
   change touches whose *why* is not recorded — it becomes a question in step 6.
2. **Scope check.** If the request bundles independent product decisions or subsystems, separate
   them rather than blending unrelated decisions into one task-spec.
3. **Open a task-spec.** `spec_create` a `task-spec` at **`.thinkrail/context/TASK-<slug>.md`** (id,
   title, status: draft, parent: the nearest relevant module). This gitignored file is the one
   temporary design artifact; update it as answers land.
4. **Bug?** When the request reports something that behaves wrongly, follow `fixing-a-bug.md` now;
   it returns here at step 5 (the "bug" is really a feature) or step 8.
5. **Product phase.** Interview what the change is for before how to build it: why it is needed,
   for whom, what the user will see and do — including empty, error, and edge states — and how we
   will know it is done. Ask in rounds per the **asking-user-questions** concept skill until no such
   decision is left assumed; look facts up instead of asking them. Record the answers in the
   task-spec's **Product** section, then confirm that understanding with one inference-confirmation
   question before any technical choice — skip only when the request itself supplied all of it.
6. **Technical phase.** Interview the technical decisions that the product answers leave open:
   constraints, compatibility, how the change will be verified, and the *why* of any decision noted
   in step 1. If you can name an alternative you rejected, especially where the code lives (server
   or browser, contract or display), show it with the trade-off instead of deciding silently. Record
   the **Design** section: the chosen approach and why, trade-offs that matter, explicit deferrals.
7. **Self-review, then review once.** Remove placeholders, contradictions, accidental scope
   expansion, and ambiguous requirements; then present one cohesive design scaled to the change.
   Ask for approval only when the request has not already approved it; revise the task-spec if the
   user adjusts it.
8. **Build.** Implement against the accepted design. Before handoff, self-review the task diff: no
   silent lint/type suppressions, duplicated nontrivial derivations, rationale left as code
   comments, or remnants of a replaced pattern.
9. **Amend specs.** Follow `amending-specs.md`.

Skipped questions or a host with no question UI are not blockers: record the best assumption in the
task-spec as unconfirmed and continue.

## What a good task-spec looks like

- Scoped to one piece of work, sized to it — a few lines for a small change.
- **Request**, **Product** (or **Bug** for the bug branch), **Design**, unconfirmed assumptions, and
  explicit deferrals.
- Temporary: its durable content moves into the owning specs at step 9 instead of being copied.

## Red flags — stop

- You are editing source code before the design is accepted.
- "It's small" or "the request already says what to do" — the workflow scales down, it does not
  switch off.
- You offered technical options before the product phase was settled.
- The task-spec has a Design section the user hasn't seen.
- You are about to hand off without step 9 — the specs drift from the code one skipped change at a
  time.

## Ending

`amending-specs.md` ends this workflow. PR lifecycle work, if requested, then enters
**shipping-a-pr** separately.
