Qskill Brainstorming

Brainstorming Ideas Into Designs

Language: Write the documents this skill produces in Vietnamese — headings, prose, business rules, edge cases, test case names. Language: Talk to the user in Vietnamese. Keep code, identifiers, file paths, commands and type names in their original form.

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

Start by classifying how much process the request needs, then work through your path: understand the context, refine the idea, present a design, and get your human partner's approval.

The same holds for HOW the work runs: explore, research and write inline in this session. Dispatching a subagent — to research, to draft, to implement — is the user's decision, not yours. See subagent-gate.

Four Paths

Before your first question, classify the request and say the classification out loud — "this looks bounded, so I'll go straight to a short plan instead of writing a spec". If you landed on bounded or architectural, stop there and confirm it (see "Confirm The Classification"); spike and bug have their own gates and skip this one.

• Spike — a feasibility question ("can we...", "is it possible...", "quick and dirty is fine") whose output is an answer, not code you keep. Present the question and what you'll try in 2-3 sentences, get a nod, then find out as cheaply as correctness allows. No spec, no plan — but the answer is written down: record it as a research doc following writing-research, then report findings as a recommendation; anything you built stays labeled throwaway.
• Bug — wrong behavior: a runtime error, a wrong result, a failing test, a regression, something that used to work and no longer does. Do not brainstorm a design for a symptom. Stop this path and invoke the qskill-systematic-debugging skill to find the root cause first. With the root cause in hand, come back here, classify the fix (usually bounded; architectural if the structure has to change), and continue on that path.
• Bounded — a well-scoped change to code that already exists in this repo: a new flag, a small endpoint, a one-file fix. Understanding the kind of app is not enough — bounded means the flow you are changing is already here to read. If there is no existing flow to change, the task is not bounded. Ask the clarifying questions that matter; in chat raise ONLY what your human partner has to decide (open questions, choices, trade-offs) — do not restate the whole design there. Once no questions are left, do NOT write a spec: invoke the qskill-write-ba-plan skill to write a short plan, and let that skill handle the file, the commit and the review gate (see "Bounded Goes To write-ba-plan").
• Architectural — new projects, new subsystems, changes that restructure how components fit together or alter interfaces others depend on. Follow the full process: questions, approaches, sectioned design, written spec, then the write-ba-plan skill. Everything about approaches, design presentation and the spec document itself lives in writing-specs — read it before exploring approaches.

When in doubt between two paths, take the heavier one and say so while asking — doubt is a reason to ask better, never a reason to skip the gate.

After the gate the ratchet is one-way: hidden complexity discovered mid-task upgrades the path — stop, say so, and step up. Nothing downgrades mid-task. The gate is the ONE place a path can move down, and only because your human partner moved it.

Confirm The Classification

Ask with AskUserQuestion, in Vietnamese, with one sentence of reasoning for the path you picked. Two options, and the second one depends on where you landed:

• Classified bounded → 1. Đúng, tiếp tục · 2. Nâng lên architectural
• Classified architectural → 1. Đúng, tiếp tục · 2. Hạ xuống bounded

Take their answer as given; do not argue the label. Why this gate exists: the bounded/architectural line is drawn by intent, and intent lives with your partner, not in the diff.

Commits Apply To Every Path

Read this while you classify — the commit rules bind every path, not just the architectural one. Skipping the full spec does not skip the commit; a bounded fix landing uncommitted is exactly the mess this rule exists to prevent.

Git gate, before any path starts: run git rev-parse --git-dir. If this is not a Git repository, STOP and ask the user to initialize Git. Do not probe, do not implement, do not write a document. Without version control, several tasks pile up in one working tree and the commits that eventually get made are dirty.

Every commit carries a slug, as the subject prefix [<slug>]. The slug is always the path's own document filename minus its extension, date included — YYYY-MM-DD-<topic> — so the whole work stream stays groupable from git log --oneline --grep. Never strip the date. Which document, and the exact commit format, belong to the path:

Before reporting done on any path, run git status --porcelain. Anything still listed is unfinished work: commit it, or say explicitly what you left uncommitted and why. Full rules: commit-convention.

Bounded Goes To write-ba-plan

Bounded writes no spec, but it still leaves a document behind — and that document is a plan, not a file format of its own.

Why: a bounded task can still stretch across several sessions. In a later session your human partner runs qskill-executing-plans to carry on, and that skill reads only plan documents under docs/superpowers/plans/. A design parked in a spec or a bespoke brief file leaves nothing to execute — so bounded and architectural funnel into the same single document type.

When no questions are left: say briefly that you are moving on to write the plan, then invoke the qskill-write-ba-plan skill. From that point everything — plan content, file path, slug, commits, the user review gate, the handoff to qskill-executing-plans — follows that skill's rules. Do not restate or reinvent those rules here.

The one difference from architectural: a bounded task has no spec document, so in the plan header the Spec: field reads none (bounded task) followed by a sentence or two summarizing the request and why this approach was chosen — that is the record someone reads later to learn why the change was made this way.

The approval gate is unchanged: you do not write code in the turn where you hand over. The plan gets written, committed, reviewed by your human partner, and only then implemented.

Anti-Pattern: "Too Simple To Need Approval"

Every path ends with your human partner approving your intent before implementation. A todo list, a single-function utility, a config change — the plan may be a few lines, but you MUST put it in front of your human partner and get approval. "Simple" tasks are where unexamined assumptions cause the most wasted work. What scales with simplicity is the artifact, never the approval.

Red Flags

Checklist

Classify first, announce the path, and — for bounded or architectural — get it confirmed. Then create a task for each item on the confirmed path and complete them in order. If your partner moves the level, drop that checklist and run the other one from the top.

Spike:

1. Explore project context — enough to frame the probe
2. Present question + probe plan — 2-3 sentences
3. Get approval — a nod on the probe is enough
4. Investigate — as cheaply as correctness allows
5. Write the research doc — per writing-research: write it, self-review, commit it
6. Commit or delete what you built — throwaway probes get deleted; anything kept is committed under the research slug, then git status --porcelain must be clean
7. Report findings — a recommendation; label anything built as throwaway

Bug:

1. Invoke qskill-systematic-debugging — before anything else; no guessing, no patching the symptom
2. Report root cause — state the real cause and the evidence for it
3. Re-classify the fix — bounded or architectural, then run that path's checklist in full (approval gate and plan document included)

Bounded: 0. Confirm the classification — ask: tiếp tục / nâng lên architectural; nothing below starts before the answer

1. Explore project context — check files, docs, recent commits
2. Ask clarifying questions — one at a time, the ones that matter
3. Raise in chat only what your partner must decide — open questions, choices between approaches, trade-offs; do not restate the whole design
4. Invoke qskill-write-ba-plan — once no questions are left; a short plan, with Spec: reading none (bounded task) plus a summary of the request and why this approach was chosen
5. Follow that skill's rules from there — it owns the plan file, slug, commits, the user review gate, and the handoff to qskill-executing-plans

Architectural: 0. Confirm the classification — ask: tiếp tục / hạ xuống bounded; nothing below starts before the answer

1. Explore project context — check files, docs, recent commits
2. Ask clarifying questions — one at a time, understand purpose/constraints/success criteria
3. Read writing-specs — it owns approaches, design presentation, spec content and the spec document
4. Propose 2-3 approaches — with trade-offs and your recommendation
5. Present design — in sections scaled to their complexity, get user approval after each section
6. Write design doc — per writing-specs: write it, then commit it
7. Spec self-review — per the same reference; fix inline
8. User reviews written spec — ask user to review the spec file before proceeding
9. Transition to implementation — invoke write-ba-plan skill to create implementation plan

Process Flow

digraph brainstorming {
    "Classify: spike / bug / bounded / architectural" [shape=diamond];
    "Bounded: tiếp tục / nâng lên?" [shape=diamond];
    "Architectural: tiếp tục / hạ xuống?" [shape=diamond];
    "Invoke qskill-systematic-debugging" [shape=box];
    "Report root cause; re-classify the fix" [shape=box];
    "Present question + probe (2-3 sentences)" [shape=box];
    "Ask clarifying questions (bounded)" [shape=box];
    "Raise only what the user must decide" [shape=box];
    "Invoke write-ba-plan skill (bounded)" [shape=doublecircle];
    "Human approves probe?" [shape=diamond];
    "Investigate" [shape=box];
    "Write research doc + commit" [shape=box];
    "Report recommendation" [shape=doublecircle];
    "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 write-ba-plan skill" [shape=doublecircle];
    "Hidden complexity? Upgrade path" [shape=box];

    "Classify: spike / bug / bounded / architectural" -> "Present question + probe (2-3 sentences)" [label="spike"];
    "Classify: spike / bug / bounded / architectural" -> "Invoke qskill-systematic-debugging" [label="bug"];
    "Classify: spike / bug / bounded / architectural" -> "Bounded: tiếp tục / nâng lên?" [label="bounded"];
    "Classify: spike / bug / bounded / architectural" -> "Architectural: tiếp tục / hạ xuống?" [label="architectural"];
    "Bounded: tiếp tục / nâng lên?" -> "Ask clarifying questions (bounded)" [label="tiếp tục"];
    "Bounded: tiếp tục / nâng lên?" -> "Explore project context" [label="nâng lên"];
    "Architectural: tiếp tục / hạ xuống?" -> "Explore project context" [label="tiếp tục"];
    "Architectural: tiếp tục / hạ xuống?" -> "Ask clarifying questions (bounded)" [label="hạ xuống"];
    "Invoke qskill-systematic-debugging" -> "Report root cause; re-classify the fix";
    "Report root cause; re-classify the fix" -> "Classify: spike / bug / bounded / architectural";
    "Present question + probe (2-3 sentences)" -> "Human approves probe?";
    "Ask clarifying questions (bounded)" -> "Raise only what the user must decide";
    "Raise only what the user must decide" -> "Invoke write-ba-plan skill (bounded)" [label="no questions left"];
    "Human approves probe?" -> "Investigate" [label="yes"];
    "Investigate" -> "Write research doc + commit";
    "Write research doc + commit" -> "Report recommendation";
    "Hidden complexity? Upgrade path" -> "Classify: spike / bug / bounded / architectural";
    "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 write-ba-plan skill" [label="approved"];
}

Terminal states are path-bound. Architectural: the ONLY skill you invoke after brainstorming is qskill-write-ba-plan — never any other implementation skill. Bounded: also ends at qskill-write-ba-plan — the only difference is that no spec document precedes it. Spike: the terminal state is a committed research doc plus a reported recommendation. Bug: the terminal state is a root cause plus a re-classification — the fix runs on its own path.

The Process

The subsections below are shared by every path that designs something — bounded and architectural alike. A spike stops at "present the probe, get a nod" and then records the answer per writing-research.

The architectural-only depth — exploring approaches, presenting the design in sections, and every rule about the spec document — lives in writing-specs. For bounded work, context plus a few questions plus a short in-chat design is the whole process.

Understanding the idea:

• Check out the current project state first (files, docs, recent commits)
• Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
• If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
• For appropriately-scoped projects, ask questions one at a time to refine the idea
• Prefer multiple choice questions when possible, but open-ended is fine too
• Only one question per message - if a topic needs more exploration, break it into multiple questions
• Focus on understanding: purpose, constraints, success criteria

Design for isolation and clarity:

• Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
• For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
• Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
• Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.

Working in existing codebases:

• Explore the current structure before proposing changes. Follow existing patterns.
• Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
• Don't propose unrelated refactoring. Stay focused on what serves the current goal.

Delegation

GATE FIRST: ../shared/subagent-gate.md — the user decides whether this run uses subagents at all. Propose the split below, stop for their answer, and run inline until it comes.

REQUIRED REFERENCE once they choose subagents: ../shared/subagent-delegation.md — capability check, role selection (Oh-My-Pi: role task, backup tiny), the lead contract, the dispatch prompt contract.

When subagents are available you are the lead: you hold the conversation, the classification and the design judgment; subagents do the reading. Fan them out in parallel — the units here are independent by nature.

Delegate (parallel, one output file each):

• Surveying the current project state: structure, existing patterns, relevant modules, recent commits.
• One agent per open question that needs code or docs read to answer it.
• Spike probes: one agent per candidate approach, each reporting findings against the same question.

Never delegate:

• Asking the user questions, or interpreting their answers. One voice talks to the user — yours.
• The classification decision and its confirmation.
• The design itself, or the spec / research document. You write those from what the subagents found.

Wait for the batch, read the reports, and only then ask your next question — questions built on a guess you could have delegated are wasted turns.

Path References

The rest of the process is path-specific. Read only the file for the path you classified into:

• Spike — writing-research: where the research doc goes, its header, content rules, self-review and commit.
• Architectural — writing-specs: exploring approaches, presenting the design, spec content rules, the spec document, its commit, self-review and the user review gate.
• Bounded — no reference file here; invoke qskill-write-ba-plan and follow that skill.
• Bug — no reference file here; invoke qskill-systematic-debugging, then re-classify.