record

Files (6)

• SKILL.md
• index-template.md · assets/
• madr-4.0.0-template.md · assets/
• spec-archival.rst · references/
• subagent.rst · references/
• adr-scan.sh · scripts/

SKILL.md (first lines)

## Codex execution

Delegation is optional. Read references/subagent.rst only when delegation is useful or requested. It does not install a named agent or grant permissions.

# Architecture Decision Records

Capture why a significant decision was made, in MADR 4.0.0, at the moment it is
made. Answer later "why did we choose X?" questions from the records instead of
from memory. Records are durable project memory for people and agents. A wrong
or invented rationale is worse than no record, so evidence rules come first.

When the MADR format itself matters (field names, status values), verify against
the canonical [MADR site](https://adr.github.io/madr/) and the
[4.0.0 template](https://github.com/adr/madr/blob/4.0.0/template/adr-template.md).
Being wrong would mislead every later reader.

## Consent gate

Applies to every write below: new records, the index, status edits and
directory setup.

1. **Offer, don't write.** At a decision moment, say in one or two sentences what
   you would record and ask. Example: "That settles queue vs. cron polling.
   Record it as ADR-0007?" Offer once per decision. If the user declines or
   ignores it, drop it and write nothing.
2. **Show before writing.** Present the full draft, the target path, the index
   row, and any edit to an older record. Write only after an explicit yes. A yes
   to "record it" covers that draft. It does not cover unrelated edits, a commit,
   or a push.
3. **Retrieval is read-only.** Answering questions never needs consent and never
   writes.

## Decision moments

Offer a record when the session:

- chooses between two or more viable options for structure, a dependency,
  framework or service, a data model, an interface or protocol, a deployment
  topology, or a security or compliance posture;
- accepts a quality trade-off (latency vs. cost, consistency vs. availability);
- makes a choice that is costly to reverse or that other teams will build on;
- rejects a tempting option for a reason that someone will otherwise rediscover
  ("we tried X, it fails because …"). Rejections are worth recording too;
- reverses or contradicts an existing accepted ADR (offer a superseding record).

Do not offer for routine, local or easily reversed choices: naming, formatting,
a library's internal API, a bug fix, or anything the code already states
plainly. One decision per record. Split multi-part decisions.

## Locate the records

Run the scanner from the repository root before numbering, drafting or
answering:

```bash
bash <skill-dir>/scripts/adr-scan.sh next    # dir, exists, index, style, highest, next, others
bash <skill-dir>/scripts/adr-scan.sh list    # number, status, date, title, path (TSV)
bash <skill-dir>/scripts/adr-scan.sh check   # duplicate numbers, unindexed records
```

`<skill-dir>` is this skill's installed directory. The scanner honours an
adr-tools `.adr-dir` file. It then checks, in order: `docs/adr`,
`docs/decisions`, `doc/adr`, `docs/architecture/decisions`,
`docs/architecture-decisions`, `adr`, `decisions`. With no records anywhere, the
default is `docs/adr/`. If `others=` is non-empty, the repository has several
ADR directories. Ask which one is authoritative and don't merge them.

If the scanner cannot run, compute the same result by hand. Do not skip the
history check.

### Numbering and file names

- **Use `next=`.** It is one above the highest number in the files, the index
  links, `ADR-NNNN` mentions in the index, and ADR files anywhere in git history
  on every local and fetched ref. Numbers are never reused. A deleted record or
  an unmerged branch's record keeps its number. Gaps are fine.
- **Branch collisions.** Two branches can still claim the same number. Run
  `git fetch` first when the user agrees. If `check` reports a duplicate after a
  merge, renumber the record that has not merged yet. Never renumber a merged
  one.
- **Name style.** New directories use `NNNN-title-with-dashes.md`, which is
  MADR's convention: four digits, lowercase, imperative or noun phrase.
  Existing directories keep their style. `style=adr-NNNN-` means the
  repository uses the legacy `adr-NNNN-slug.md` names, so match them. Never
  rename existing files.

### Existing formats

Follow an established house format if the directory already has one: Nygard
(`## Status` / `## Context` / `## Decision` / `## Consequences`), the coded
`POS-001` / `NEG-001` style, or another. Consistency inside one log beats
conversion. Never rewrite old records into MADR. Use MADR for new logs, or when
the user asks for it.

## Record a decision

1. **Gather evidence.** Use only the session, the user, and repository
   artefacts (issues, PRs, specs, benchmarks, code). For each MADR field, note
   where its content came from.
2. **Ask before guessing.** If drivers, options or the reason for the choice are
   missing, ask one compact round of targeted questions. Anything still unknown
   is written as `Not recorded — <the open question>`. It is never filled in
   with plausible text.
3. **Draft from [assets/madr-4.0.0-template.md](assets/madr-4.0.0-template.md).**
   Delete unused optional sections and the template comment. House rules on top
   of MADR:
   - `status: "proposed"` unless the user confirms the decision is made, in
     which case use `"accepted"`. `date` is today, in ISO format.
     `decision-makers` lists only people the user names. Don't infer them from
     git authors.
   - **Drivers first.** The outcome sentence repeats the chosen option's title
     verbatim from Considered Options. Its `because` clause names at least one
     driver.
   - **Real alternatives only.** Each option was seriously considered and
     appears in the evidence. Never add a straw-man option. Doing nothing is a
     real option only if someone proposed it.
   - **Honest consequences.** List at least one `Bad, because` for the chosen
     option, or state plainly that none was identified. Each rejected option
     gets the reason it lost.

From nq-rdl/agent-extensions, MIT.

More from nq-rdl/agent-extensions