Brainstorming

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 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:

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

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

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.