Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
First Response — Be Fast
Your first message MUST be a clarifying question. Do NOT explore files, create tasks, or research anything before asking the first question. Get the conversation moving immediately.
Triage — Scale Process to Scope
After 1-2 questions, assess scope:
| Scope | Signals | Process |
|---|---|---|
| Small | Config change, UI tweak, single-file feature, clear requirements | Questions → Design (verbal) → Approval → Implement |
| Medium | Multi-file feature, some unknowns, new component | Questions → Design → Approval → Write spec → Implement |
| Large | New system, architecture decision, multiple subsystems, unfamiliar tech | Questions → Research → Design → Write spec → Self-review → Grill-me → Implement |
Default to small unless evidence says otherwise. Create tasks only for medium/large scope.
The Process
Ask Clarifying Questions
- Ask questions one at a time — don't overwhelm
- Prefer multiple choice when possible
- Focus on: purpose, constraints, success criteria
- Explore context (files, docs, commits) lazily — only when a question requires it, and do it in the background while asking
- If the request describes multiple independent subsystems, flag it immediately and help decompose before diving in
Research Prior Art (large scope only)
Only fires for large scope: architecture decisions, new systems, greenfield features, library/tool selection, unfamiliar patterns.
Launch one background subagent while continuing questions. Prefer octocode MCP tools (githubSearchCode, githubViewRepoStructure) when available; fall back to GitHub search. If no external search tools exist, skip silently.
Before proposing approaches, present a short Prior Art section:
- 2-4 bullet points max, readable in 30 seconds
- What was found, which projects, what pattern they used
The user reacts before you propose approaches.
Propose Approaches
- Propose 2-3 different approaches with trade-offs
- Lead with your recommendation and explain why
- Reference prior art when available
Present the Design
- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
- Ask after each section whether it looks right
- Cover: architecture, components, data flow, error handling, testing
- Be ready to go back and clarify
Design for isolation and clarity:
- Break into smaller units with one clear purpose and well-defined interfaces
- Each unit should be understandable and testable independently
- Smaller, well-bounded units are easier to work with — better reasoning, more reliable edits
Working in existing codebases:
- Explore the current structure before proposing changes. Follow existing patterns.
- Where existing code has problems that affect the work, include targeted improvements as part of the design
- Don't propose unrelated refactoring
Write Spec (medium/large only)
- Write to
docs/specs/YYYY-MM-DD-<topic>-design.md(user preferences override this) - Commit the design document
Spec self-review (large only):
- Placeholder scan — any TBD, TODO, incomplete sections? Fix them.
- Internal consistency — do sections contradict each other?
- Scope check — focused enough for a single implementation plan?
- Ambiguity check — any requirement interpretable two ways? Pick one.
Fix issues inline and move on.
User review gate:
"Spec written and committed to
<path>. Review it and let me know if you want changes before implementation."
Stress-Test (large only)
After user approves the spec:
"Before we build — I recommend
/vs-grill-meon this design to find what breaks before code is written. Skip withnoto go straight to implementation."
Transition to Implementation
Proceed to plan mode or begin implementation based on the approved design.
Key Principles
- Fast first response — ask, don't explore
- Scale to scope — small features get light process
- One question at a time — don't overwhelm
- YAGNI ruthlessly — remove unnecessary features
- Explore alternatives — propose 2-3 approaches before settling
- Incremental validation — present design, get approval before moving on