agentleFS
Sign inStart free
renathoazrenathoaz/arsyn/skills/ideating/SKILL.md

ideating

Skill2 starsChanged 8 months agoMITView on GitHub

Structured requirement discovery before implementation.

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 7 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do NOT invoke any implementation skill, write code, or scaffold until a design is presented and the user approves it.

    line 11
  2. Distinctive:

    Read project files, docs, recent commits.

    line 18
  3. Distinctive:

    If the request spans multiple independent subsystems, flag it immediately.

    line 19
  4. Distinctive:

    When upcoming questions involve UI, layout, diagrams, or visual comparisons, offer the playground plugin.

    line 23
  5. Very specific:

    If accepted, read skills/ideating/references/playground-guide.md before proceeding.

    line 27
  6. Very specific:

    Use AskUserQuestion calls to gather requirements — not freeform paragraphs.

    line 33
  7. Distinctive:

    Prefer multiple-choice when feasible.

    line 36
  8. Distinctive:

    Prefer small files — you reason and edit more reliably within bounded context.

    line 59
  9. Very specific:

    Write the approved design to docs/arsyn/specs/YYYY-MM-DD-<topic>-design.md (user preference overrides path).

    line 65
  10. Distinctive:

    Ask user to review the committed spec.

    line 67

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free