# decisions-starter.md

A portable starter for a decision-log file that AI coding tools consult
on every change. Pattern lifted from [SPF](https://spf.hosette.net) and
[Omunikorudo](https://omnichord.hosette.net), where it keeps rejected
features rejected, design rules from drifting, and scope from
re-litigating itself every sprint.

The premise: with AI tooling, building is cheap. Deciding what's not
worth building, and keeping it decided, is the work. A rule that lives
in a file the system reads on every change beats a style guide nobody
reads.

---

## How to use it

1. Drop a copy at the root of your project. Rename to something obvious
   (`decisions.md`, `mem.md`, or paste it directly into your `CLAUDE.md`
   if you're using Claude Code).
2. Add the prompt at the bottom of this file to your agent's system
   instructions, so the agent reads `decisions.md` on every change.
3. Edit freely. Each section is a category; each entry is a decision
   with a date and a one-line reason.

The file is a working artifact, not documentation. When a decision
reverses, edit in place and add `[reversed YYYY-MM-DD]` rather than
deleting. The "never quietly edit history" discipline is what makes
the file load-bearing instead of decorative.

---

## Rejected ideas

A list of features and patterns that came up, got considered, and got
cut. Each entry is short. The point is that the agent sees them on
every turn and stops re-suggesting them.

- **YYYY-MM-DD** Pomodoro mode as a separate feature. Cut; the
  single-task focus shape did the work without a timer.
- **YYYY-MM-DD** Per-task estimator. Cut. Estimates are a category
  error for this product.
- **YYYY-MM-DD** Third sprint column. Cut. Two columns is the
  discipline; a third would let me defer indefinitely.

## Design rules

Conventions the surface follows that aren't worth re-deriving every
time. Cite a specific instance if possible.

- **YYYY-MM-DD** No em-dashes in body copy. Use a comma, semicolon,
  or period. Em-dashes in commit messages are fine.
- **YYYY-MM-DD** Headings are lowercase: `## why`, `## what I built`.
  Convention is intentional.
- **YYYY-MM-DD** No third-party tracker. No analytics. The colophon
  promises this; the codebase has to keep the promise.

## Naming conventions

How things in this product are named, and the metaphor each name
carries. If a name doesn't constrain the implementation, it's
wallpaper.

- **YYYY-MM-DD** "Sprint protection," not "sprint planning." The
  product is for the practitioner, not the program.
- **YYYY-MM-DD** "Focus Mode," not "Pomodoro Mode." Focus is the
  noun that survives a missed timer.

## Scope guardrails

What this product is not, and what surfaces would pull it toward
becoming a different product.

- **YYYY-MM-DD** Not Linear. Not Jira. Not Asana. Building for the
  practitioner's own week, not the team's reporting structure.
- **YYYY-MM-DD** No recorder, no looper. Those features pull toward
  a DAW-lite category; the product is the instrument, not the studio.

---

## Agent prompt to wire this up

Add this to your project's `CLAUDE.md`, system prompt, or
`.cursorrules`:

> Before making any change to this codebase, read `decisions.md` at
> the project root. Treat every entry as binding. Specifically:
> rejected ideas stay rejected, design rules don't drift, naming
> conventions are load-bearing, and scope guardrails are not
> negotiable. If a request would violate an entry in `decisions.md`,
> flag the conflict before acting. If a decision needs to change,
> propose the edit to `decisions.md` first, with a reason and the
> date, before changing the code.

---

## Why this shape

A few notes from running this in production across several projects.

**One file, not a folder.** A directory of decision docs gets read
once and then ignored. A single file gets re-read on every turn.
Volume is the enemy.

**Dated entries, not just bullets.** The date is what lets you trust
the entry six months from now. It's also what makes "reversed
YYYY-MM-DD" notes legible.

**The prompt is part of the artifact.** The file does nothing without
the agent prompt that tells the agent to read it. Ship them together
or neither works.

**Decisions before features.** Adding a new feature should require
adding or referencing a decision. If a feature can't justify itself
in `decisions.md`, it's probably the wrong feature.

The full live decision log behind SPF isn't published; the *shape*
is. This template is the shape.