Decision Logger

Decision Logger

Automatically logs architectural decisions in ADR (Architecture Decision Record) format.

When to Use

Log a decision when:

• Choosing a technology stack
• Selecting a library over alternatives
• Defining project structure
• Making trade-off decisions
• Changing established patterns

ADR Format

## ADR-{number}: {title}

**Date:** {YYYY-MM-DD}
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX

### Context
{What is the issue we're seeing that motivates this decision?}

### Decision
{What is the change we're proposing/​have agreed to implement?}

### Consequences

**Positive:**
- {benefit_1}
- {benefit_2}

**Negative:**
- {tradeoff_1}
- {tradeoff_2}

**Neutral:**
- {implication}

### Alternatives Considered

| Alternative | Why Rejected |
|-------------|--------------|
| {option_1} | {reason} |
| {option_2} | {reason} |

Process

1. Check for docs/​DECISIONS.md

test -f docs/​DECISIONS.md || mkdir -p docs && touch docs/​DECISIONS.md

If file doesn't exist, create with header:

# Architecture Decision Records

This document captures significant architectural decisions made during development.

Format: [ADR (Architecture Decision Record)](https://adr.github.io/)

---

2. Determine Next ADR Number

Parse existing file for highest ADR number:

ADR-001, ADR-002, ... → next is ADR-003

3. Gather Decision Details

Required fields:

• title: Short description (e.g., "Use SQLite for storage")
• context: Why this decision is needed
• decision: What was chosen
• consequences: Impact of the decision
• alternatives: What else was considered

4. Append to File

Add new ADR at the end of docs/​DECISIONS.md.

Integration Points

With /​craft

During project creation, automatically log:

• ADR-001: Technology Stack
• ADR-002: Project Structure
• ADR-003: Database Choice (if applicable)

With /​why

/​why reads from docs/​DECISIONS.md to provide context for past decisions.

With /​next

When implementing features that require architectural choices, prompt to log decision.

Example Decisions

Technology Stack

## ADR-001: Rust + Axum for Backend

**Date:** 2025-01-15
**Status:** Accepted

### Context
Building a notes app that needs fast response times (<50ms) and single-binary deployment.

### Decision
Use Rust with Axum web framework.

### Consequences

**Positive:**
- Sub-millisecond response times achievable
- Single binary, no runtime dependencies
- Memory safety guarantees

**Negative:**
- Steeper learning curve than Go or Node.js
- Longer compile times
- Smaller ecosystem for web libraries

### Alternatives Considered

| Alternative | Why Rejected |
|-------------|--------------|
| Go + Chi | Less type safety, wanted stronger guarantees |
| Node + Hono | Not single binary, runtime required |
| Python + FastAPI | Too slow for <50ms requirement |

Database Choice

## ADR-002: SQLite for Persistence

**Date:** 2025-01-15
**Status:** Accepted

### Context
Single-user notes app needs persistent storage. Simplicity and portability are priorities.

### Decision
Use SQLite with sqlx for database operations.

### Consequences

**Positive:**
- Zero configuration required
- Database is a single file (portable)
- Fast for single-user workloads
- Compile-time SQL checking with sqlx

**Negative:**
- No concurrent write support
- Limited to single machine
- Manual migration management

### Alternatives Considered

| Alternative | Why Rejected |
|-------------|--------------|
| PostgreSQL | Overkill for single-user, requires setup |
| In-memory | Data lost on restart, requirement violation |
| File-based JSON | No query capabilities, slow for large data |

Output

After logging, confirm:

Logged: ADR-{number} "{title}"
View: docs/​DECISIONS.md
Query: /​why {topic}