docs/design-docs/index.md

# 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