# Decision Records

This directory contains the project's decision records, organized by domain. Decisions are the **source of truth** for all architectural, design, scope, and process choices.

## Domain Files

| File | Domain | Contents |
|------|--------|----------|
| `architecture.md` | Architecture | Technical foundation — how we build, tools, patterns, infrastructure |
| `scope.md` | Scope | Project concept, target audience, platform, feature boundaries |
| `process.md` | Process | Team workflow, communication, development process |
| `questions.md` | Open Questions | Unresolved questions requiring team discussion |
| `rejected.md` | Rejected | Options considered and rejected, with rationale |

## Decision Types

- **D-NNN** — Confirmed decisions (active or superseded)
- **Q-NNN** — Open questions awaiting resolution
- **R-NNN** — Rejected alternatives (kept for historical context)

## Adding a Decision

1. Choose the appropriate domain file
2. Assign the next available ID in sequence
3. Use this format:

```markdown
### D-NNN: Decision title
- **Date:** YYYY-MM-DD
- **Decision:** What was decided
- **Rationale:** Why this option was chosen
- **Raised by:** Who proposed or surfaced the question
- **Dissent:** Any disagreement, or "None"
```

4. Run `make decisions-sync` to update the SQLite index

## Querying Decisions

### Via CLI (preferred)

```bash
# List all active confirmed decisions
make decisions-active

# Find decisions without associated tickets
make decisions-orphan

# Check decision-to-ticket coverage
make decisions-coverage
```

### Via SQLite wrapper

```bash
# All active decisions
db/connectors/sqlite-query "SELECT id, domain, title FROM decisions WHERE status='active' AND type='confirmed' ORDER BY domain, id"

# Decisions in a specific domain
db/connectors/sqlite-query "SELECT id, title FROM decisions WHERE domain='architecture' AND status='active'"

# Search by keyword
db/connectors/sqlite-query "SELECT id, domain, title FROM decisions WHERE title LIKE '%keyword%' OR decision LIKE '%keyword%'"

# Decisions linked to a specific ticket
db/connectors/sqlite-query "SELECT d.id, d.title FROM decisions d JOIN tickets t ON d.id = t.decision_ref WHERE t.id = 42"

# Open questions
db/connectors/sqlite-query "SELECT id, title FROM decisions WHERE type='question' AND status='active'"
```

### Via Qdrant (semantic search)

```bash
db/connectors/qdrant-search "asymmetric information design"
```

## Superseding a Decision

When a decision is replaced:

1. Add `- **Status:** Superseded by D-NNN` to the original
2. Reference the original in the new decision's rationale
3. Run `make decisions-sync`