# Decision Register

A one-page format for deciding a batch of items quickly: audit findings, rules or policies to reconcile, proposals, backlog or risk triage.

Each item is a card. A card holds:
- what is happening, in plain English, with evidence;
- the text it should be judged against;
- where it lives and where it came from;
- a recommendation;
- buttons: Keep / Remove / Discuss by default, or any choices you configure.

The page also has these features:
- "Start here" puts the most urgent items first.
- A progress tally.
- Filters by group, by class and for undecided items, plus search.
- "Use my recommendation" on each card.
- An optional note per card.
- Export with "Copy my decisions as text" or "Download decisions (JSON)".

Open `sample/register.html` in a browser to try it. The sample is a fictional "unwritten team rules" review with nine cards.

## Where it came from

The format was devised with Claude (Anthropic's AI assistant, running in Claude Code) in October 2026. The trigger was an audit of rules that software agents had been following although nobody had approved them. That review produced 140 decisions, and the person deciding them asked to keep the format for similar work.

It is not an industry-standard template. It borrows from familiar practices: decision logs and architecture decision records, review checklists, triage boards and "accept the recommendation" workflows.

## Three ways to use it

### 1. With Claude Code (recommended)

Copy this folder into your skills directory:

```bash
cp -R decision-register-kit ~/.claude/skills/decision-register
```

Then, in any session, ask for the format. For example: "Audit our deploy scripts against the release policy and give me the results as a decision register."

Claude follows `SKILL.md`:
1. Gathers findings without changing anything.
2. Writes one card per decision.
3. Builds the page.
4. On claude.ai, publishes it as an artifact that stores your decisions.
5. When you say you're done, reads your decisions back and acts on them.

Other agents that read `SKILL.md`-style instructions can use the same folder.

### 2. By hand

1. Copy `examples/config.example.json` and `examples/items.example.json`, then edit them. The fields are described below.
2. Build:
   ```bash
   python3 scripts/build.py --config my-config.json --items my-items.json --out out
   ```
3. Open `out/register.html` in a browser, or send it to whoever decides.

Decisions are saved in that browser. To collect them, have the decider use "Download decisions (JSON)" or "Copy my decisions as text" and send you the result.

### 3. Hosted

`register.html` is a single static file, so any static host works. Outside claude.ai, each visitor's decisions stay in their own browser. On a claude.ai artifact with the `db` capability, decisions are shared and Claude can read them.

## Requirements

- Python 3.8 or later, standard library only.
- A current browser.
- Fonts load from Google Fonts. Without a network connection the page falls back to system fonts.

## Config fields

| Field | Purpose |
|---|---|
| `title`, `eyebrow` | Page title and the small line above it |
| `ledeHtml`, `metaHtml[]`, `howHtml[]` | Introduction, one-line facts, and "how to read this" paragraphs |
| `labels` | Wording for card sections and buttons |
| `classes[]` | How an item relates to the reference: `key`, `label`, `tallyLabel`, `tone`, `filter` |
| `options[]` | The decision buttons: `key`, `label`, `tone` |
| `recommendations{}` | Recommendation keys. Each has a `label` and the `option` it selects (`null` means "your call") |
| `groups[]` | Sections of the page: `key`, `label`, `short`, `intro` |
| `pathRoots{}` | Short prefixes in `where` that the page expands into full paths |
| `answersTitle`, `answers[]` | Optional direct answers to questions asked up front |
| `startHere` | Title and introduction for the priority list |
| `infoSections[]` | Rows that need no decision, such as coverage or items checked and found consistent |
| `evidenceTitle`, `evidence[]` | Supporting files (`source`, `path`, `label`) copied next to the page |
| `collection` | Database collection name on claude.ai (default `decisions`) |
| `storageKey` | Browser storage key. Use one per register |

Tones are `red`, `amber`, `blue`, `green`, `violet` and `gray`.

The `*Html` fields and `answers[].html` are inserted as HTML, so put only your own trusted content there. Card fields are always inserted as plain text.

## Item fields

| Field | Required | Purpose |
|---|---|---|
| `id` | yes | Letters, digits, `-`, `_` |
| `group`, `cls`, `rec` | yes | Keys from the config |
| `title` | yes | What happens, in plain words |
| `does` | yes | Who or what is affected, when, with evidence |
| `ref` | | The governing text, quoted briefly |
| `status` | | Where it applies today |
| `where[]` | | Exact locations |
| `origin` | | Where it came from |
| `recText` | | One sentence: what to do |
| `priority` | | `true` lists the card under "Start here" |

`SKILL.md` has guidance on writing good cards.

## Files

```
README.md                    this file
SKILL.md                     instructions for Claude Code or another agent
LICENSE                      MIT
assets/template.html         the page
scripts/build.py             validates the data and writes register.html
examples/config.example.json sample configuration
examples/items.example.json  sample cards
sample/register.html         the sample, already built
```