decision-auto-tracker

Files (21)

• SKILL.md
• README.md · evals/
• evals.json · evals/
• README.md · evals/files/repo-derived/decisions/
• decision-log.json · evals/files/repo-derived/decisions/
• 2026-08-05-01-sample-buffer-holds-16-readings.md · evals/files/repo-derived/decisions/log/
• 2026-08-05-02-uplink-port-12-carries-health.md · evals/files/repo-derived/decisions/log/
• AGENTS.md · evals/files/repo-stored/
• 2026-08-01-01-postgres-for-order-store.md · evals/files/repo-stored/decisions/log/
• 2026-08-01-02-checkout-timeout-30s.md · evals/files/repo-stored/decisions/log/
• 2026-09-10-01-sku-is-the-product-key.md · evals/files/repo-stored/decisions/log/
• 2026-09-10-02-eu-region-only-for-launch.md · evals/files/repo-stored/decisions/log/
• trigger-eval.json · evals/
• config.md · references/
• format.md · references/
• triage-rubric.md · references/
• audit-manifest.mjs · scripts/
• check-append-only.sh · scripts/
• new-decision.mjs · scripts/
• validate.mjs · scripts/
• template.md

SKILL.md (first lines)

## Purpose

Repos accumulate many small decisions per week — pick this tool, name this entity that, skip this feature for v1, settle on this threshold. Most never reach an ADR. They live in chat history and disappear.

This skill turns those moments into a _decision log_ under `decisions/log/`: one file per decision, structured frontmatter, fixed body, sortable filenames. A future session greps the log instead of re-deciding the same thing.

The log is _not_ a replacement for formal ADRs. ADRs carry full context for architecturally significant choices and live wherever the repo keeps them. The log is for the rest.

The log is only useful while it stays **short and true**. Audits of real logs show the two ways it degrades: entries that nobody will look up (a quarter of all entries), and entries that bundle several choices into one file (one in seven). The rules below exist to prevent both.

## What to capture

Capture when the user **commits to a choice** and that choice passes the durability test. Ask three questions; log when at least two answers are **yes**:

1. Will a teammate need this **after the current ticket or PR closes**?
2. Would a **new contributor** six months from now be surprised not to know it?
3. Does it **constrain future code, data or behaviour**, rather than describe one execution path?

Strong signals:

- Picking between debated options: "let's go with B", "use Cloudflare not Route 53", "shaped diffs, not full snapshots"
- Locking in a value, name, owner or threshold: "call it `Pasture`", "default timeout is 500 ms", "Dana owns the ingest service"
- Settling an open question: "skip subscriptions for v1", "no Bluetooth in the first hardware cut"
- Reversing or superseding a prior decision: "scratch that, switch back to Postgres"
- Explicit request: "log this decision", "track that", "remember we decided X"

## What not to capture

| Looks like a decision, but is… | Example | Where it belongs instead |
| --- | --- | --- |
| **A task pick** — how to finish this ticket, PR or session | "ship it as a standalone PR", "waive the local test run, open the PR", "close TICKET-911 with the gap recorded", "base the fix on fresh main" | the ticket or PR |
| **An agent-harness rule** — how the AI agent itself operates | "one AI review round per PR", "the stop-hook falls back to WSL", "MCP config lives in `~/.codex`", "dispatch the reviewer only for behavioural diffs" | `AGENTS.md` / `CLAUDE.md`, or the repo that owns the skill or hook |
| **A task instruction** | "write a function that does X" | nowhere |
| **Brainstorming** — no commitment yet | "we could maybe use Redis here… or memcached" | wait until they commit |
| **A style preference or code-level correction** | "be more concise", "rename foo to bar" | nowhere |
| **A clarification** of an existing entry | "the 500 ms debounce also applies on re-entry" | the existing entry (see Workflow step 5) |

Exception: in a repo whose product _is_ agent tooling (a skills repo, a hooks library), decisions about that tooling are ordinary technical decisions.

**When a task pick wraps a durable rule, split them.** "Ship the decoder only; we never build a daily view for this report — the dashboard reads raw rows" contains one task pick (ship the decoder) and one durable rule (no daily view). Log the rule alone, in two sentences. Leave the pick in the ticket.

When in doubt, apply the three questions and, if still unsure, ask the user in one line.

## One decision per file

Each file holds **one choice** that can be cited on its own:

- `## Decision` is one or two sentences. Background goes to Context, rationale to Reasoning.
- The filename slug is 2–6 words. The H1 title carries the long form.
- A message with several independent picks becomes several files with consecutive sequence numbers.

An entry that opens with "Four picks for…" or "Three choices, shipped as one PR:" is the anti-pattern. A future reader wants to supersede one of the four and cannot.

## Storage layout and config

```
decisions/
├── decision-log.json   # optional per-repo config (see references/config.md)
├── NNN-….md            # formal ADRs, if the repo keeps them here (never touched by this skill)
└── log/                # this skill writes here
    ├── 2026-05-18-01-pasture-replaces-piquete.md
    └── …
```

The `decisions/log/` folder is created on first capture. Without a config the defaults apply: `status` is stored in each file, the log may be edited, no `bucket` field. A config can switch to a **derived-status, append-only** log, add a required `bucket` classification, restrict the `linear` pattern, and set a ratchet date for the length rules. Read [`references/config.md`](references/config.md) when a `decision-log.json` exists — the supersede and clarification steps differ by mode.

## Filename

`YYYY-MM-DD-NN-short-slug.md` — the date the decision was made, a zero-padded per-day sequence, and a 2–6 word kebab-case slug. `scripts/new-decision.mjs` derives all three; use it rather than hand-writing frontmatter. Two parallel sessions can still allocate the same `NN`; the validator reports the collision and the later entry is renumbered.

## File format

```markdown
---
id: 2026-05-18-01
date: 2026-05-18
topic: pasture-replaces-piquete
status: active
tags: [glossary, terminology]
linear: ABC-387
supersedes:
---

# Pasture replaces Piquete

## Decision

**Pasture** is the canonical term. **Piquete** appears only as a labelled source term, never as the canonical name.

## Context

Reviewing the glossary, we found `Piquete` and `Pasture` used interchangeably across docs. New contributors could not tell which one the code should use. The question came up while updating ABC-387.

## Reasoning

`Pasture` is the industry-standard English term and matches the product name. `Piquete` is region-specific and belongs as a labelled mapping.

## Source

User in conversation, 2026-05-18: "Always use `Pasture`/`Herd`, not `Piquete`/`Mali`; source terms only as labelled mappings."
```

### Frontmatter fields

| Field        | Required                       | Format                                         | Notes                                                                                                              |
| ------------ | ------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `id`         | yes                            | `YYYY-MM-DD-NN`                                | Must match the filename prefix                                                                                     |
| `date`       | yes                            | `YYYY-MM-DD`                                   | Must match the date portion of `id`                                                                                |
| `topic`      | yes                            | kebab-case slug, 2–6 words                     | Must match the filename slug                                                                                       |
| `status`     | `statusMode: stored` (default) | `active` \| `superseded` \| `reversed`         | Omit in `derived` mode — the validator computes it from the `supersedes` graph                                     |
| `bucket`     | only when the config lists buckets | one of the configured names                | What a later rewrite must carry forward; see the repo's config                                                     |
| `tags`       | yes                            | inline YAML list of kebab-case strings          | `[]` if none. Reuse existing tags before inventing new ones                                                        |
| `linear`     | optional                       | tracker id matching the config pattern          | Default pattern `ABC-123`; empty if none                                                                           |
| `supersedes` | optional                       | id, `id-slug`, or inline list `[a, b]`          | On the **new** entry. Use the `id-slug` form when two files share an id                                            |

### Body sections

Exactly these four `##` sections, in this order. None may be empty or left as a `TODO` stub.

From Kotivskyi/skills, MIT.

More from Kotivskyi/skills