Shape a delivery direction with ak:brainstorm

Use ak:brainstorm to turn an unclear product, code, documentation, or maintenance request into a delivery contract and a recommended direction. The Skill separates desired outcomes from current evidence, compares only meaningful choices, and stops before implementation.

Choose ak:brainstorm when the direction needs work

Use ak:brainstorm when

• A multi-step request lacks a clear outcome, constraint, non-goal, or acceptance criterion.
• More than one viable technical or product approach deserves comparison.
• A diagnosed bug still has a material architecture or repair choice.
• You want an evidence-backed recommendation before planning or implementation.

Choose another workflow when

• The contract and direction are already accepted. Use ak:plan to produce an implementation plan or ak:cook to execute approved work.
• You need a direct technical answer rather than a delivery decision. Use an advisory or question workflow.
• You need a bounded map of the codebase. Use ak:scout.
• You have only a failure symptom. Diagnose the root cause before selecting a fix; brainstorming does not substitute for debugging.

Prepare the project and runtime

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the runtime and scope you are using.
• State the problem, affected users or systems, known constraints, and any decisions that are already settled.
• Open the relevant project when feasibility depends on its code, tests, documentation, or design guidance.
• Define whether the run may create a local brief or use advisory supervision.

See Runtime adapters for target-level differences.

Run the Skill

/ak:brainstorm "Choose how to add offline draft recovery to the editor. Preserve current storage formats, avoid a new service, and define observable recovery behavior."

/ak:brainstorm "Choose how to add offline draft recovery to the editor. Preserve current storage formats, avoid a new service, and define observable recovery behavior."

$ak:brainstorm "Choose how to add offline draft recovery to the editor. Preserve current storage formats, avoid a new service, and define observable recovery behavior."

The topic or problem is the default input. The available options change the output, scope handling, verification, supervision, or visual treatment:

With --report, the Skill uses plans/{plan-dir}/reports/ when a plan is active, otherwise plans/reports/, unless the runtime injects a Report: path. The report contains the four contract fields, compared options, recommendation, and unresolved questions; --report --html writes both artifacts.

With --advice, the Skill always uses the one-shot kongming supervisor. Model routing depends on the host: Claude Code subscription sessions use Fable 5, Codex uses gpt-6-astra with low reasoning effort, and Cursor uses claude-fable-5-high. Other single-model hosts use their strongest available session model and report that same-model limitation.

When the topic touches UI or UX, --html includes annotated interface mockups and a delivery-flow diagram. For approach comparisons, the Skill reads ak config prefs resolve --json and prefers a diagram-design Quadrant when .prefs.visual.diagramDesign.enabled; for KPI-shaped tiles, it prefers AntV Infographic CandyCardLite or CompactCard when .prefs.visual.antv.enabled. If richer image generation is unavailable, the Skill can fall back to local HTML, CSS, or SVG and reports that limitation.

When --ultra is selected, the Skill keeps the candidate work read-only, requires five usable candidates with one bounded re-dispatch if needed, anonymizes them before scoring, and records a short ranking appendix. It hard-stops when parallel read-only candidate dispatch is unavailable. If the runtime cannot route model tiers but can dispatch in parallel, the Skill reports a same-tier best-of-5 run. It is inspired by LLM-as-a-Verifier, but does not claim logprob or tournament mechanics.

When --yagni is selected, the Skill passes the literal flag to downstream Skills and delegated work. Without it, the handoff does not introduce scope-cutting.

Describe the decision clearly

Useful input names:

• Outcome: the user-visible or operational state you want.
• Constraints: compatibility, safety, time, technology, or ownership limits.
• Non-goals: adjacent work the decision must not absorb.
• Acceptance criteria: observable evidence that will prove the direction succeeds.
• Known evidence: current behavior, prior decisions, failed approaches, or repository areas worth inspecting.

For the draft-recovery example, say which editor state must survive, when recovery should appear, what existing format must remain readable, and that no new network service is allowed. The Skill can then compare bounded options instead of inventing a broader synchronization platform.

Understand what happens during a run

1. The Skill frames the contract. It captures the outcome, constraints, non-goals, and acceptance criteria, reusing an accepted contract when one already exists.
2. The Skill checks proportionality. A concrete request receives a concise confirmation. A question is asked only when a missing decision materially changes the result, safety boundary, or public contract.
3. The Skill inspects relevant evidence. It reads the smallest useful set of source, tests, documentation, plans, or live state before claiming an approach is feasible. It resolves uncertainty that this evidence can settle and labels only what remains unknowable at decision time.
4. The Skill routes failures through diagnosis. For a bug, it captures the failing state and root cause before comparing cause-aligned repairs.
5. The Skill compares viable approaches. It presents up to three meaningful options, their trade-offs, evidence gaps, load-bearing assumption, and first failure condition. It compares their worst plausible cases, then recommends the smallest approach that satisfies the contract. If a critical assumption cannot be resolved, the recommendation favors the option that is cheapest to abandon.
6. The Skill prepares the handoff. It passes the accepted contract, chosen direction, evidence, and unresolved risks to planning, implementation, or the bug-fix workflow.

Keep approval and safety with you

You decide whether to accept the recommendation and whether a material disagreement is resolved. Advisory supervision does not take that authority. The Skill should not inspect unrelated private files, claim current behavior from intent alone, or create extra components and migrations merely to make a design appear complete.

The local HTML brief is an explicit file effect. Network assets are not required for it, and the brief should remain directly openable from disk. Any downstream commit, push, pull request, publication, deployment, credential use, or paid service needs separate authority in the workflow that performs it.

Verify the result

A complete run should give you:

• The accepted outcome, constraints, non-goals, and acceptance criteria.
• Confirmed evidence and clearly labeled gaps or uncertainty.
• Up to three viable approaches when a real choice exists.
• Each approach's load-bearing assumption, first failure condition, and worst plausible case.
• A recommended direction with rationale, meaningful trade-offs, and switching cost when a critical assumption remains unresolved.
• A handoff target such as ak:plan, ak:cook, or a diagnosed bug workflow.
• Unresolved risks or questions listed last.
• When requested, a self-contained brainstorm.html brief with the same decision record and required visual explanation.

The run is complete when you can explain what will be delivered, what is outside scope, why the selected direction fits the evidence, and what observable checks will prove success. It is not evidence that the solution has been implemented.

Troubleshoot or continue

After accepting the direction, continue with ak:plan for a durable implementation plan or ak:cook for approved execution. Use the Engineer Kit overview to compare nearby workflows.

Know the current limits

• The Skill can inspect only the project state, tools, and credentials available in the current session.
• It can establish a decision contract, not implementation feasibility beyond the evidence it actually inspects.
• Cursor slash invocation is user-verified evidence, not proof of full runtime parity.