Guides interactive module design via Q&A before writing. Use when the user wants to design a module, class, or feature together, or when they say "/spec-design".
Guides a collaborative, question-first design process. Do not write design docs until ambiguities are clarified.
Always start with clarifying questions. Do not propose a design or write a doc until the user answers.
Read relevant code (e.g. docs/overview.md, related src/ modules, config) to ground your questions. Then ask questions in categories below.
Ask 1–2 questions per category as needed. Adapt to context; not all apply.
| Category | Examples |
|---|---|
| Path / terminology | "You said directory—do you mean file? resolveX() returns a file path." |
| Data flow | "Where does X come from—caller, config, or generated internally?" |
| "Is this a factory, a repository, or both? What does it own vs delegate?" |
| Semantics | "Does 'resume' mean load history into context, or just set a flag?" |
| Concurrency | "Same ID—allow multiple instances? Do we need caching?" |
| Error handling | "File missing on resume—throw or return Result? Overwrite on create?" |
| Injection | "Config via constructor injection or direct import?" |
If something contradicts existing code or docs, ask immediately.
docs/designs/{module-name}.mdSessionManager → session-manager.md)Design doc structure (adjust as needed):
# {ModuleName} Design
One-line summary.
## Dependencies
- Imports, paths, config
## API
- Method signatures and behavior
## Error Handling
- When to throw, no graceful fallback
## Concurrency / Constraints
- Single-writer, no cache, etc.