| name | trail-decisions |
| description | Candidate: Keep a decision trail (a.k.a. show-your-work) while implementing, so a later reviewer can audit the choices and not just the diff. A TSV appended one row per real decision (what, why, evidence), written in the moment, never reconstructed. Use at the start of any implementation task an agent runs unattended or that a human reviews after stepping away. Consumed by review-gate's choice-audit lens. Experimental and awaiting baseline evaluation. |
| compatibility | Requires a writable canonical Railly Skills source repository. The self-audit step wants a reviewer runtime on a different model family than the writer. |
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 checkout through , , or ; the canonical resolver is . Start there at the start of the task. Never place the trail in the target repo, , , 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:
