ideating

name	ideating
description	Structured requirement discovery before implementation.

Ideating

Investigate context, interview the user, converge on an approved design, then hand off to arsyn:planning.

Do NOT invoke any implementation skill, write code, or scaffold until a design is presented and the user approves it. No exceptions — even for "trivial" tasks. A short design is fine; no design is not.

Phases

1. Reconnaissance

• Read project files, docs, recent commits.
• If the request spans multiple independent subsystems, flag it immediately. Decompose into sub-projects before refining details. Each sub-project runs its own ideate-plan-execute cycle.

2. Playground Offer (visual work only)

When upcoming questions involve UI, layout, diagrams, or visual comparisons, offer the playground plugin. This is its own message — no other content.

"Some decisions ahead may be easier to evaluate visually. I can use the playground to show mockups, diagrams, and comparisons in a browser. Want to try it?"

If accepted, read skills/ideating/references/playground-guide.md before proceeding. If declined, continue text-only.

Even after acceptance, decide per-question: use playground only when seeing something beats reading about it.

3. Structured Interview

Use AskUserQuestion calls to gather requirements — not freeform paragraphs.

• One question per turn. Multiple questions per message overwhelm.
• Prefer multiple-choice when feasible; open-ended when exploring.
• Focus on: purpose, constraints, success criteria, edge cases.
• Tag assumptions you are making so the user can correct them.

4. Approach Comparison

Present 2-3 approaches with trade-offs. Lead with your recommendation and why. Never present a single "obvious" option — the user may hold context you lack.

5. Sectioned Design Presentation

Present the design in sections scaled to complexity. After each section, confirm before continuing.

Tag each section:

• [CONFIDENCE: HIGH] — clear requirement, clear path
• [CONFIDENCE: MEDIUM] — reasonable but assumption-laden
• [CONFIDENCE: LOW] — best guess, needs validation
• [CONFIDENCE: NEEDS INPUT] — blocked without user input

Cover as applicable: architecture, components, data flow, error handling, testing strategy.

6. Design Principles

• Units with one clear purpose, well-defined interfaces, independently testable.
• Prefer small files — you reason and edit more reliably within bounded context.
• In existing codebases, follow established patterns. Improve code you touch; do not propose unrelated refactoring.
• YAGNI ruthlessly.

7. Document and Review

1. Write the approved design to docs/arsyn/specs/YYYY-MM-DD-<topic>-design.md (user preference overrides path). Commit it.
2. Dispatch spec-document-reviewer subagent (see references/spec-document-reviewer-prompt.md) with crafted review context — never raw session history. Fix issues and re-dispatch until approved (max 3 iterations, then surface to user).
3. Ask user to review the committed spec. Wait for approval before proceeding.

8. Handoff

Invoke arsyn:planning to produce an implementation plan. No other skill.

Gotchas

• "Too simple for a design" — Every task gets a design. Simple tasks get short designs, not no design. This is the single most common skip.
• Multiple questions per message — Strict one question per turn. Batching questions wastes turns when answers invalidate each other.
• Premature implementation — After a few questions Claude gets eager. The HARD-GATE exists because this happens reliably.
• Single-option proposals — Always 2-3 approaches. The "obvious" one is often wrong once the user adds context.
• Oversized specs — Match spec length to task complexity. 20-line change does not need 2000-word spec.
• Forgetting to commit the spec — Save and git commit before moving to planning.
• Playground for non-visual questions — "What should this API return?" is not a visual question. Reserve playground for layout, color, diagram, and comparison work.
• Freeform interview — Use structured AskUserQuestion calls, not walls of text with embedded questions.