Skip to content

Trevoke/org-gtd.el / .claude/skills/architect

architect

Verified

Use when requirements exist and a technical design is needed before implementation begins

/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:

SectionContent
OverviewWhat we're building and why this approach
ComponentsEach new/modified module with its responsibility
Data FlowHow data moves through the system
API SurfacePublic functions — signatures and behavior
Error HandlingWhat can go wrong and how we handle it
Testing StrategyWhat 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

MistakeFix
Presenting one design as "the answer"Always propose 2-3 approaches with tradeoffs
Not reading the codebase firstExplore before proposing. Name specific files and patterns.
Designing without interviewingAsk the user which approach. They decide direction.
Including full implementation codeDesign describes WHAT and WHY. /implement handles HOW.
Producing the entire design in one shotPresent 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 stepAlways end with: "use /implement when ready"
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall