brainstorming

name	brainstorming
description	Use before any DevOps build, change, or new feature — refine requirements through dialogue before touching infrastructure or code

Brainstorming Ideas Into Designs

Help turn DevOps ideas into fully formed designs and specs through natural collaborative dialogue.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.

Do NOT touch infrastructure, write configs, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY request regardless of perceived simplicity.

Anti-Pattern: "This Is Too Simple To Need A Design"

Every change goes through this process. A single environment variable, a one-line Nginx config, a cron job — all of them. "Simple" changes are where unexamined assumptions cause the most production incidents. The design can be short (a few sentences for truly simple changes), but you MUST present it and get approval.

Checklist

You MUST complete these in order:

1. Explore project context — check files, docs, recent commits, existing infra
2. Ask clarifying questions — one at a time, understand purpose/constraints/success criteria
3. Propose 2-3 approaches — with trade-offs and your recommendation
4. Present design — in sections scaled to their complexity, get user approval after each section
5. Write design doc — save to docs/specs/YYYY-MM-DD-<topic>-design.md and commit
6. Spec self-review — quick inline check for placeholders, contradictions, ambiguity, scope
7. User reviews written spec — ask user to review before proceeding
8. Transition to implementation — invoke writing-plans skill to create implementation plan

Process Flow

digraph brainstorming {
    "Explore project context" [shape=box];
    "Ask clarifying questions" [shape=box];
    "Propose 2-3 approaches" [shape=box];
    "Present design sections" [shape=box];
    "User approves design?" [shape=diamond];
    "Write design doc" [shape=box];
    "Spec self-review\n(fix inline)" [shape=box];
    "User reviews spec?" [shape=diamond];
    "Invoke writing-plans skill" [shape=doublecircle];

    "Explore project context" -> "Ask clarifying questions";
    "Ask clarifying questions" -> "Propose 2-3 approaches";
    "Propose 2-3 approaches" -> "Present design sections";
    "Present design sections" -> "User approves design?";
    "User approves design?" -> "Present design sections" [label="no, revise"];
    "User approves design?" -> "Write design doc" [label="yes"];
    "Write design doc" -> "Spec self-review\n(fix inline)";
    "Spec self-review\n(fix inline)" -> "User reviews spec?";
    "User reviews spec?" -> "Write design doc" [label="changes requested"];
    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
}

The terminal state is invoking writing-plans. Do NOT invoke any implementation skill directly.

The Process

Understanding the idea:

• Check out the current project state first (files, docs, recent commits, existing infra)
• Before asking detailed questions, assess scope: if the request covers multiple independent systems, flag this immediately. Don't refine details of a project that needs to be decomposed first.
• For appropriately-scoped changes, ask questions one at a time
• Prefer multiple choice questions when possible
• Focus on: purpose, constraints, success criteria, blast radius, rollback plan

DevOps-specific questions to ask:

• What problem is this solving? What's broken or missing today?
• What scale? (traffic, data size, team size, environments)
• What constraints? (cloud provider, budget, existing stack, compliance)
• What does success look like?
• What's the blast radius if this goes wrong?
• Is this reversible? What's the rollback plan?
• Can this be rolled out gradually?

Exploring approaches:

• Propose 2-3 different approaches with trade-offs
• Present options with your recommendation and reasoning
• Lead with your recommended option and explain why

Presenting the design:

• Once you understand what you're building, present the design
• Scale each section to its complexity
• Ask after each section whether it looks right so far
• Cover: architecture, components, data flow, error handling, rollback, testing
• Be ready to go back and clarify

Working in existing environments:

• Explore the current state before proposing changes. Follow existing patterns.
• Where existing infra has problems that affect the work, include targeted improvements — the way a good engineer improves what they're working in.
• Don't propose unrelated refactoring. Stay focused on what serves the current goal.

After the Design

Documentation:

• Write the validated design (spec) to docs/specs/YYYY-MM-DD-<topic>-design.md
• Commit the design document to git

Spec Self-Review: After writing the spec, look at it with fresh eyes:

1. Placeholder scan: Any "TBD", "TODO", or vague requirements? Fix them.
2. Internal consistency: Do sections contradict each other?
3. Scope check: Is this focused enough for a single implementation plan?
4. Ambiguity check: Could any requirement be interpreted two ways? Pick one, make it explicit.

Fix issues inline. No need to re-review — just fix and move on.

User Review Gate: After self-review, ask the user to review the written spec:

"Spec written and committed to <path>. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."

Wait for the user's response. Only proceed once the user approves.

Implementation:

• Invoke the writing-plans skill to create a detailed implementation plan

Key Principles

• One question at a time — don't overwhelm
• YAGNI — don't design for hypothetical future scale
• Reversibility — prefer reversible changes, flag irreversible ones
• Blast radius — always ask: what breaks if this goes wrong?
• Incremental — can this be rolled out gradually?
• Explore alternatives — always propose 2-3 approaches before settling
• Incremental validation — present design, get approval before moving on
• Multiple choice preferred — easier to answer than open-ended when possible
• Be flexible — go back and clarify when something doesn't make sense