nledford/engineering-review-board / skills/brainstorming
brainstorming
VerifiedStructured ideation for ambiguous software engineering work. Use when agents need to generate multiple options, compare tradeoffs, or converge on a recommendation before implementation, architecture, domain modeling, API design, migration, refactor, testing strategy, or debugging choices after systematic reproduction. Do not use for simple mechanical tasks, obvious single-path fixes, or active unexplained symptoms; use systematic-debugging first.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
SKILL.md
View on GitHub---
name: brainstorming
description: Structured ideation for ambiguous software engineering work. Use when agents need to generate multiple options, compare tradeoffs, or converge on a recommendation before implementation, architecture, domain modeling, API design, migration, refactor, testing strategy, or debugging choices after systematic reproduction. Do not use for simple mechanical tasks, obvious single-path fixes, or active unexplained symptoms; use systematic-debugging first.
---
# Brainstorming
Use this skill to make option generation explicit before choosing a path. The
goal is better engineering judgment, not more ceremony.
## When to use
Load this skill when the task has meaningful uncertainty or more than one
plausible path:
- ambiguous product or engineering requirements;
- architecture, domain modeling, API design, migration, refactor, or testing
strategy decisions;
- debugging choices after systematic reproduction has produced credible
hypotheses or solution paths to compare;
- planning that benefits from divergent thinking before convergence;
- decisions where maintainability, domain alignment, testability, simplicity,
performance, security, operability, or migration cost may point in different
directions.
## When not to use
Skip brainstorming when it would add ceremony without changing the outcome:
- simple, mechanical, formatting-only, generated, or already-specified tasks;
- tasks with an obvious single correct implementation;
- small fixes where reading the code and making the narrow change is enough;
- situations where the next honest step is direct repository inspection,
reproduction, tests, or validation rather than ideation.
Route active unexplained symptoms to
[`systematic-debugging`](../systematic-debugging/SKILL.md) before brainstorming.
Use brainstorming only after reproduction establishes evidence sufficient to
compare hypotheses or solution paths.
## Workflow
1. **Frame the problem.** Restate the goal, constraints, known facts, and desired
outcome in repository or domain language.
2. **Separate evidence.** List facts, assumptions, unknowns, and risks. Do not
invent requirements or facts that are not grounded in the prompt, issue,
repository docs, code, tests, or observed behavior.
3. **Generate options.** Produce at least two credible candidate approaches
before selecting one. Include a conservative option when appropriate.
4. **Compare tradeoffs.** Evaluate maintainability, domain alignment,
testability, simplicity, performance, security, operability, migration cost,
reversibility, and fit with existing boundaries or coverage.
5. **Converge.** Recommend one path, explain why it is better than the credible
alternatives, and name any rejected option that remains tempting.
6. **Plan validation.** Identify evidence that would validate or invalidate the
recommendation: code to inspect, tests to add or run, docs to check, metrics,
failure reproduction, or review gates.
7. **Transition.** Turn the recommendation into an actionable next step, a small
implementation sequence, or a handoff to the appropriate implementation,
methodology, debugging, or review skill.
## Output shape
Keep results concise enough for downstream implementation. Use this structure by
default and omit non-useful subsections:
```text
Problem framing
- Goal:
- Known facts:
- Constraints:
Assumptions, unknowns, and risks
- Assumptions:
- Unknowns:
- Risks:
Candidate options
1. Option A — ...
2. Option B — ...
3. Option C — ...
Tradeoff analysis
- Maintainability:
- Domain alignment:
- Testability:
- Simplicity:
- Performance/security/operability/migration cost:
Recommended approach
- Choose:
- Why:
- Rejected alternatives:
Validation plan
- Evidence to gather:
- Checks/tests/reviews:
Open questions
- Blocking only:
```
## Practice integration
- **BDD:** Use brainstorming to clarify behavior options and acceptance examples,
not to replace executable scenarios or tests. If the outcome needs durable
behavior contracts, load `behavior-driven-development` or `gherkin` next.
- **DDD:** Prefer existing domain language, boundaries, invariants, and policies
when comparing options. Load `domain-driven-design` when the model itself needs
focused design.
- **Hexagonal Architecture:** When options differ by dependency direction,
ports/adapters, use cases, or infrastructure isolation, load
`hexagonal-architecture` after choosing whether the extra indirection is worth
its cost.
- **Clean Architecture:** When options differ by use cases, interactors,
presenters, interface adapters, or concentric policy/detail boundaries, load
`clean-architecture` after deciding those responsibilities matter.
- **Onion Architecture:** When options differ by domain/application rings around
a protected domain model, load `onion-architecture` after confirming the domain
behavior justifies the layers.
- **TDD:** Use the validation plan to decide the first failing test or regression
check. Load `test-driven-development` when implementation should proceed by
Red-Green-Refactor.
## Behavior examples
```gherkin
Scenario: Ambiguous API design benefits from brainstorming
Given an agent sees two viable route or data-shape designs
When the tradeoffs affect domain boundaries, tests, or migration cost
Then the agent compares options before recommending an implementation path
```
```gherkin
Scenario: A narrow mechanical fix skips brainstorming
Given the user asks for a clearly specified typo, formatting, or one-line bug fix
When code inspection shows the implementation path is obvious
Then the agent makes and verifies the narrow change without brainstorming ceremony
```
## Anti-patterns
- Generating only one option and calling it brainstorming.
- Treating brainstorming as a substitute for reading code, docs, tests, or error
output.
- Producing vague ideas with no implementation implications.
- Overweighting quick wins when long-term maintainability, security, or domain
alignment matters.
- Ignoring existing boundaries, invariants, test coverage, or validation lanes.
- Using brainstorming to avoid making a justified recommendation.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |