File size: 1,800 Bytes
5dd1bb4 9e64e71 5dd1bb4 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | # Design Docs
This directory contains design documentation for architectural decisions — the WHY behind technical choices.
## Core Beliefs
See [core-beliefs.md](core-beliefs.md) for agent-first operating principles.
## Decisions (ADRs)
Architectural Decision Records are stored in [decisions/](decisions/).
| ADR | Title | Status |
|-----|-------|--------|
| [0001](decisions/0001-template.md) | ADR Template | Template |
## Feature Design Docs
| Feature | Status | Date | Reversibility |
|---------|--------|------|---------------|
| [Reward Shaping Research](reward-shaping-research.md) | Active | 2026-03-29 | N/A (research) |
## Creating Design Docs
Use the `design-doc` skill for structured decision documentation:
```
skill({ name: "design-doc" })
```
The skill guides you through:
1. **Context** — What's the situation? What triggered this?
2. **Decision Drivers** — Constraints, preferences, quality attributes
3. **Options Analysis** — At least 2 options with pros/cons
4. **Decision** — Choice + rationale + consequences + reversibility
5. **Implementation Guidance** — Key interfaces, boundaries
## When to Create a Design Doc
**CREATE when:**
- Making an architectural choice with multiple valid options
- Introducing a new pattern or abstraction
- Choosing between technologies, libraries, or approaches
- A decision will affect multiple features
**SKIP when:**
- Following an existing established pattern
- The decision is trivial or easily reversed
- A simple code comment would suffice
## Integration with Autocode
The `autocode-implementation-planner` skill automatically reads linked design docs:
- Uses constraints as hard requirements
- Respects the chosen interfaces
- Stays within the defined boundaries
- Notes reversibility for future refactoring
|