/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 /define or 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 /implement to 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"