decision-logging

Decision Logging Skill

When commands make architecture decisions (choosing tech stacks, patterns, frameworks, databases, etc.), they MUST log those decisions to _state.json.decisions[] for auditability and future reference.

When to Log a Decision

Log a decision whenever your command:

1. Chooses a technology (database, framework, language, messaging system, auth provider)
2. Selects an architectural pattern (monolith vs. microservices, clean vs. modular, etc.)
3. Determines a trade-off (prioritize cost over latency, scalability over simplicity, etc.)
4. Makes a significant strategic choice that affects the system's design

Do NOT log:

• Routine operations (generating files, running tests)
• Configuration of already-decided technologies
• Re-running previous decisions

Examples of decisions to log:

• ✅ "Choose PostgreSQL for primary database" (blueprint command)
• ✅ "Use React over Vue for UI framework" (scaffold command)
• ✅ "Prioritize fast iteration over peak performance" (mvp-scope)
• ✅ "Use monolithic architecture for initial MVP" (architecture design)
• ❌ "Generated auth routes file" (implementation detail, not decision)
• ❌ "Installed dependencies" (mechanical task, not decision)

Decision Structure

Each decision is a JSON object in the decisions[] array:

{
  "id": "D-NNN",
  "title": "Choose PostgreSQL for primary database",
  "rationale": "ACID compliance for order consistency. Team has PostgreSQL expertise. Query flexibility for future analytics features.",
  "alternatives_rejected": [
    "MongoDB (weak multi-document transactions, overkill for relational data)",
    "DynamoDB (cost scales poorly with joins, limited query flexibility)"
  ],
  "trade_offs": "Higher operational complexity than managed cloud DBs. Team must maintain backups. Cold-start slower than serverless options.",
  "made_by_command": "blueprint",
  "timestamp": "2026-04-24T14:32:10Z"
}

Field Details

Field	Type	Required	Description
id	string	Yes	Unique decision ID (e.g., "D-001", "D-002"). Increment sequentially within a project.
title	string	Yes	Brief decision title (3-10 words). E.g., "PostgreSQL for primary database"
rationale	string	Yes	Why this choice? What does it enable? What problem does it solve? (2-5 sentences or bullets)
alternatives_rejected	array of strings	Yes	What were the runner-up options and why did they lose? Makes future reconsideration easier. At least 2 alternatives.
trade_offs	string	Yes	What are you giving up? What becomes harder or more expensive? (1-3 sentences)
made_by_command	string	Yes	Which command made this decision? (e.g., "blueprint", "sdl", "scaffold")
timestamp	string	Yes	ISO-8601 timestamp when decision was made (e.g., "2026-04-24T14:32:10Z")