tomevault-io Design
Make technical decisions when the "how" is the problem.
When to Use
- Algorithms: Non-trivial logic that needs to be thought through
- Data structures: How things relate, what to store, how to index
- System boundaries: Where does this live? What owns what?
- Performance-sensitive code: Choices that affect speed/memory
- Security-sensitive code: Choices that affect attack surface
When to Skip
Design is overhead when the implementation is obvious:
- UI changes where spec describes the outcome
- CRUD operations
- Wiring existing pieces together
- Configuration changes
The 100 Forks Test
If you ran /prep-plan 100 times with current context:
- Forks diverge: AI invents different solutions. You need more context. Design provides it.
- Forks converge: AI finds the obvious solution. Spec is enough. Skip design.
Process
- Search for related prior work: Use the Task tool to invoke the
lore-researcheragent with the technical problem description. Do not run in background. Wait for the result before continuing. Include findings in the Context section. - Review any relevant
.lore/research/,.lore/brainstorm/, or.lore/specs/context - Clarify the technical problem - what exactly needs deciding?
- Explore approaches - at least 2-3 options with trade-offs
- Decide: Pick an approach and document why
- Define the interface/contract - how will other code interact?
- Document edge cases
- Confirm with user before saving
- Save to
.lore/design/ - Offer fresh-eyes review (see below)
Output
Save to .lore/design/[topic].md
Use kebab-case for filenames. Match spec naming where a spec exists (e.g., if spec is history-sync.md, design is history-sync.md or history-sync-dedup-algorithm.md).
Document Structure
Before writing: Load ${CLAUDE_PLUGIN_ROOT}/shared/frontmatter-schema.md to get frontmatter field definitions and status values for design documents.
---
[frontmatter per schema]
---
# Design: [Topic]
## Problem
What technical problem are we solving? Link to spec if one exists.
## Constraints
- Technical constraints
- Performance requirements
- Integration points
- Security considerations
## Approaches Considered
### Option 1: [Name]
Description of the approach.
**Pros:**
- Pro 1
- Pro 2
**Cons:**
- Con 1
- Con 2
### Option 2: [Name]
Description of the approach.
**Pros:**
- Pro 1
- Pro 2
**Cons:**
- Con 1
- Con 2
## Decision
Which approach and why. **This section is required.** A design without a decision is just research.
## Interface/Contract
How other code will interact with this:
- Function signatures
- Data structures
- Protocols
- APIs
## Edge Cases
Known edge cases and how they're handled:
- Edge case 1: Handled by...
- Edge case 2: Handled by...
## Open Questions
(Optional) Things still TBD that don't block implementation.
What vs How
Design sits between spec and plan:
| Document | Answers | Example |
|---|---|---|
| Spec | What are we building? | "Deduplicate history entries" |
| Design | How does it work? | "Use content hashing with LRU eviction" |
| Plan | How do we build it? | "Add HashIndex class in src/index.ts" |
Design is "how it works" in the abstract. Algorithms, data structures, protocols. Implementation-agnostic where possible.
Plan is "how to build it" in the concrete. Files, functions, dependencies. Implementation-specific.
Research vs Design
Both explore options. The difference is commitment:
| Document | Output | Decision Required? |
|---|---|---|
| Research | "Here are the options" | No |
| Design | "Here's what we're doing and why" | Yes |
If you're documenting options without picking one, that's research. Design requires the Decision section.
After Saving: Fresh-Eyes Review
After the design is saved, run a fresh-eyes review. Designs written in conversation accumulate assumptions. A reviewer with fresh context reads only what's on the page, catching what the author can't see.
Invoke the design-reviewer agent on the saved design using the Task tool. The agent evaluates designs through four lenses: decision quality, trade-off clarity, interface implementability, and edge case coverage. Present the findings and offer to address critical issues before moving on.
Specialized Agents
If .lore/lore-agents.md exists, consult it for specialized agents that can help with domain-specific concerns. Security, performance, or architecture experts can identify trade-offs you might miss. Invoke relevant agents via Task tool and incorporate their insights.
Linking to Specs
Design documents should reference their parent spec when one exists:
- In frontmatter:
related: [.lore/specs/history-sync.md] - In Problem section: "See Spec: history-sync for requirements."
Design documents can also stand alone for technical problems that don't have user-facing requirements.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.