Trail decisions

A diff shows what changed. It never shows the choices behind it: the buffer that got doubled, the port derived from a hash, the daemon assumed not to restart. Those choices compile and pass tests and still ship the wrong behavior — the fix looks fine, the decision was bad. The only way to review a choice is to see it stated. This skill makes the writing agent state its choices as it makes them, so the reviewer audits reasoning instead of re-deriving it from code.

It is PAPERCUTS.md for the act of building: a line captured in the moment, append-only, worthless until something else sweeps it. PAPERCUTS is swept by /pulse; this trail is swept by review-gate's choice-audit lens. One difference decides whether it earns its place: a papercut records friction you already felt, so it is self-justifying; a decision row records a choice that did not feel wrong when you made it, so its value is realized only when a second actor questions the consequence. Write the trail anyway. An honest record of what you chose is useful to the next reader even if no lens ever audits it.

1. Open the trail

Resolve the canonical Railly/skills checkout through RAILLY_SKILLS_REPO, ~/Programming/railly/skills, or ~/railly-skills; the canonical resolver is scripts/resolve-source-root.mjs. Start foundry/trails/<repo>/<YYYY-MM-DD>-<branch-or-mission>.tsv there at the start of the task. Never place the trail in the target repo, .agents/skills, .claude/skills, or another installed copy. A trail reconstructed from the finished diff is fiction: it records the choices you can now see were made, not the ones you actually weighed. Use one header row, then one row per decision:

ts	phase	decision	why	evidence	result