Walsworth-Group/physkit / skills/record-decision
record-decision
VerifiedRecord the why of a non-obvious decision: alternatives, reasons, dependencies, what would trigger a revisit.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
| assets/decision_template.md | markdown | 1.4 KB |
SKILL.md
View on GitHub---
name: record-decision
description: >-
Record the why of a non-obvious decision: alternatives, reasons, dependencies, what would trigger
a revisit.
---
# record-decision — capture the why, and when to revisit it
The reasoning behind a modeling or engineering choice is lost quickly. Within months, why the timestep
has its value, why an approximation was judged safe, or which library was rejected is no longer
recoverable, and the choice is kept or reverted without evidence. This skill writes a short, durable
rationale at the moment of decision, including the two parts most often lost: the conditions the decision
depends on, and the trigger that reopens it.
The record is short: a few sentences, not a committee document. It is not the conventions file (which
states the rules) and not the experiment journal (which logs what happened). It is the rationale behind a
choice and its expiry conditions.
## When it's worth a record
Record a decision when it is non-obvious and consequential and a future reader would otherwise have to
reverse-engineer it:
- choosing one method / library / model / parameterization / numerical scheme over a real alternative;
- an approximation or assumption a result will rest on (this links to the `frame-problem` inventory and
to a `verify` QUESTIONABLE ASSUMPTION);
- a non-obvious convention (sign, frame, normalization) adopted to resolve an ambiguity;
- a trade-off accepted (accuracy vs cost, generality vs simplicity);
- the reason for a non-obvious verification check, so a later editor does not delete a guard whose
purpose is not in the code.
Do not record obvious or trivial choices; they are noise. The test: would someone reasonably ask why this
was done this way and be unable to answer from the code?
## The fields (decision / alternatives / why / [provenance] / conditions / revisit-if)
Capture, briefly:
- **Decision** — what was chosen, concretely.
- **Alternatives considered** — the real options on the table (including "do nothing"), one line each. A
decision with no alternatives recorded reads as the only option, which is rarely true.
- **Why this one** — the reasoning and the trade-off, tied to the actual constraints (compute, accuracy,
fabrication, time, interpretability). Name the evidence if there is some.
- **Provenance** *(mandatory; every record states it)* — the authoritative source the decision is pinned
to, and its confidence: *PINNED* (read from a shipped artifact / saved model / released data / empirical
probe) · *REPORTED* (stated in a paper/doc) · *INFERRED* (from an untrusted proxy, such as leftover or
modified code) · *RECALLED* (from memory) · *REASONED* (engineering judgment resting on no external
claim about the system; use for a pure trade-off choice). When the decision rests on a fact from a
source, rank sources by authority: an artifact that can be parsed or run outranks text, which outranks
modified code, which outranks recollection. Resolve the fact to the highest authority available, and
note lower-authority sources that disagree and were quarantined. A load-bearing fact that can only
be marked INFERRED or RECALLED is not yet settled. Flag it; never build on it silently.
- **Conditions it depends on** — the assumptions/regime that make this the right call (a parameter range,
a data property, a compute budget, a deadline). These are what change underneath a decision.
- **Revisit-if** — the concrete trigger that should reopen it ("if we move beyond the dilute regime", "if
the grid exceeds 10⁶ cells", "if validation data arrives"). This field makes the record living rather
than archival.
Keep notation and links consistent with the rest of the work; reference related decisions and the
`frame-problem` artifact where relevant.
## Where it lives
Pick the tier by what the decision outlives. Every tier is an append-only record: one entry per decision,
never rewrite history, and supersede an old entry with a new one that links to it.
- **Campaign:** `campaign.md` §Decision record — the append-only tail below the signed-off contract;
separate from the project overview's §Standing constraints (the rules) and the
experiment `JOURNAL` (what happened).
- **Project:** the project overview's (`PROJECT.md`) §Durable decisions — a decision that outlives
one campaign (a project-wide convention, a shared-physics or instrument choice) and that sibling
campaigns inherit.
- **Ad-hoc session:** the session's `sessions/<date>_<slug>/NOTES.md`; graduates to the project record once
a campaign comes to depend on it.
- Trivial or short-lived work needs none.
## Composition
- `frame-problem` — a parked physical effect or a key assumption gets a decision record so its rationale
and revisit-trigger survive.
- Sign-off tracking — a timed-out or unanswered approval request is recorded
as "no sign-off obtained" at the time, never inferred later from an unrelated go-ahead. Resurface the
gap proactively, as a request probably missed rather than a refusal, and assume neither answer meanwhile.
- `verify` — the reason for a non-obvious check, and the premise behind a QUESTIONABLE ASSUMPTION verdict.
- `simulation-design` / `correctness-suite` — the rationale for a tool choice, a discretization, or a
non-obvious regression gate.
- `report` — decision records feed the methods and limitations sections: why each choice, what it rests
on.
## Bundled asset
- `assets/decision_template.md` — the record (decision · alternatives · why · [provenance] · conditions ·
revisit-if), with status and date.
## Checklist
- [ ] The decision is stated concretely, with the real alternatives (incl. "do nothing").
- [ ] The reasoning ties to actual constraints/evidence, not just preference.
- [ ] **Provenance** is recorded (mandatory) — the source the decision is pinned to + confidence
(PINNED/REPORTED/INFERRED/RECALLED, or REASONED for a pure-judgment call); an INFERRED/RECALLED
load-bearing fact is flagged unsettled.
- [ ] The **conditions it depends on** are written down.
- [ ] A concrete **revisit-if** trigger is set.
- [ ] It's in the right place (engineering record), not mixed into conventions or the journal.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |