trevoke /architect — Design Interview
Overview
Design the technical solution through conversation. Propose approaches with tradeoffs, let the user choose, then detail the chosen design.
Core principle: Lead with options, not answers. The user picks the direction.
When to Use
- Requirements exist (from
/defineor provided by user) - Technical approach needs to be decided before coding
- Multiple valid designs exist and tradeoffs matter
The Process
1. Find Requirements
Look for the most recent *-requirements.md in docs/plans/.
If none found or multiple exist, ask the user which to use. If no requirements exist at all, suggest /define first.
2. Explore the Codebase
Before proposing anything, understand what exists:
- How does the codebase handle similar features?
- Which files will be touched?
- What patterns are already established?
- How are similar features tested?
Name specific files and patterns you found. Don't hand-wave about "the existing architecture."
3. Propose 2-3 Approaches
For each approach:
### Approach A: [Name] (Recommended)
**Summary:** One sentence.
**How it works:** Key components and interactions.
**Pros:** Why this is good.
**Cons:** Why this might not be ideal.
**Risk:** What could go wrong.
**Fits existing patterns:** How it aligns with what's already in the codebase.
Lead with your recommendation but explain why the others exist.
4. Interview — Let the User Choose
Use AskUserQuestion:
- Which approach do they prefer?
- Any constraints you missed?
- Acceptable tradeoffs?
One question at a time. Don't dump all decisions at once.
5. Detail the Chosen Design
Present in sections, validating each with the user before moving on:
| Section | Content |
|---|---|
| Overview | What we're building and why this approach |
| Components | Each new/modified module with its responsibility |
| Data Flow | How data moves through the system |
| API Surface | Public functions — signatures and behavior |
| Error Handling | What can go wrong and how we handle it |
| Testing Strategy | What to test, at what level |
Design principles to consider:
- Does the code model the domain naturally? (DDD)
- Single responsibility — each module does one thing
- Does it feel like idiomatic Emacs Lisp?
- Are we building only what's needed? (YAGNI)
6. Save and Commit
Derive name from requirements doc (same <name> slug).
docs/plans/YYYY-MM-DD-<name>-design.md
Commit: docs: add <name> design
7. Next Step
Design saved. When ready, use
/implementto plan and execute the implementation.
Common Mistakes
| Mistake | Fix |
|---|---|
| Presenting one design as "the answer" | Always propose 2-3 approaches with tradeoffs |
| Not reading the codebase first | Explore before proposing. Name specific files and patterns. |
| Designing without interviewing | Ask the user which approach. They decide direction. |
| Including full implementation code | Design describes WHAT and WHY. /implement handles HOW. |
| Producing the entire design in one shot | Present section by section, validate each with user. |
| Hand-waving about "existing patterns" | Be specific: "org-gtd-organize.el uses transient at line 42" |
| Not referencing next step | Always end with: "use /implement when ready" |