ideating

Files (9)

• SKILL.md
• playground-guide.md · references/
• spec-document-reviewer-prompt.md · references/
• visual-companion.md · references/
• frame-template.html · scripts/
• helper.js · scripts/
• server.cjs · scripts/
• start-server.sh · scripts/
• stop-server.sh · scripts/

SKILL.md (first lines)

# Ideating

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

<HARD-GATE>
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.
</HARD-GATE>

## 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.

From renathoaz/arsyn, MIT.

More from renathoaz/arsyn