ScriptedAlchemy Before following this workflow, read the Codex runtime contract. It defines plugin paths, model configuration, delegation, and persistence.
Show me your work
Keep one canonical log.
The format
A single TSV file, one row per decision. Cells stay single-line. Evidence is a pointer, not prose.
Copy references/decision-log-template.tsv (the header row) to start a clean log. Columns:
- ts. ISO8601 timestamp.
- phase. The phase or workstream.
- decision. What was chosen or done, one line.
- why. The reason in plain words. If a principle drove it, say it plainly, not as a jargon tag.
- evidence. A link or path that proves it: commit SHA, PR number,
file:line, or an artifact, trace, or screenshot path. Never a paragraph. - result. The outcome or predicate state:
tests green,reverted,pixel-diff 0,INCONCLUSIVE,open.
An example, plain-spoken so a reviewer reads it at a glance. This is illustration only. Don't copy these rows into a real log.
ts phase decision why evidence result
2026-05-24T09:02:00Z frame counted the work first, about 100 components and roughly 75 hours wanted to know the size before starting a long run commit 3a9f1c2 found 5 things to sort out before starting
2026-05-24T09:40:00Z harness took screenshots of the old version before changing anything so we can compare old against new and catch any visual change scripts/snapshot.sh, baseline/ saved 120 reference screenshots
2026-05-24T11:15:00Z widget moved the widget styles over without changing how it looks keep the change small and the result identical commit 7c21e0a, pixel-diff 0 looks identical, tests pass
2026-05-24T12:30:00Z widget threw out a helper's work because its screenshots were blank checked the real files instead of trusting its summary worktree reset reverted, tightened the instructions for next time
Logging a row
Write each entry the way you'd tell a teammate what you did. Plain words, concrete actions, no AI speak or abstract jargon (the unslop skill applies to log text too).
Use the helper scripts/log.sh <logfile> <phase> <decision> <why> <evidence> <result>. It stamps ts, writes the header on first use, strips stray tabs/newlines, and prefixes any cell starting with =, +, -, or @ with a single quote. A bare printf appending a row works too, but mind those same bytes if cells come from generated or user-supplied text.
Log decision points and checkpoints, not every action: a fork chosen, a unit completed with its verification result, a pivot or revert with its trigger, a blocker surfaced, a gate fixed. For loop runs, one row per iteration. Skip the trivial and self-evident.
Where it lives
By default the log is a working artifact, not committed. Keep it at decisions.tsv in the work dir, or .audit/<task-slug>.tsv when several efforts run at once, and leave it out of git.
Commit it only when the work is ambitious enough that a reviewer needs the trail to trust the result.
Rules
- One row is one decision or checkpoint.
- Append-only. A wrong call gets a new row that supersedes it. Never edit or delete history.
- Prefer evidence produced by committed scripts over hand-made one-offs (the encode-lessons-in-structure principle skill).
Audit the log against the transcript
At the end of the run, before handing back, check the log told the truth. Read this run's transcript under ~/.codex/sessions/YYYY/MM/DD/*.jsonl, filtered to files whose first session_meta.payload.cwd equals the current workspace. Don't glob across ~/.codex/sessions/. That reads unrelated private chats. Walk the log against what actually happened:
- Every row maps to a real action. Cut invented or aspirational entries.
- Each row's evidence resolves and shows what the row claims.
- A fork, pivot, or abandoned approach that shaped the work but isn't logged is a gap. Add it.
- Drop padding.
Fix the log, not the story. If the work diverged from what a row claims, the row is wrong.
Cross-model review of the trail
Before handing back, spawn a subagent on a different available model from the one that did the work. Self-review is not a substitute. The subagent reads the audit trail and the run's transcript, then flags what the user should pay attention to. Not a redo of the work, a scan for what's suboptimal or risky.
- Decisions logged with weak or absent evidence.
- Verification steps skipped or claimed without proof in the transcript.
- Choices that look risky in hindsight (premature, scope-creeping, papering over a symptom).
- Gaps the user would otherwise miss on a casual skim.
Every reply for a run that produced a trail ends with an "Attention" section. Lead with the reviewer's model on its own line (reviewed by <model>), then list each flag pointing to specific rows or moments. "No flags" is a valid value. The model name is not.
Reviewing the trail
Read top to bottom, follow the evidence pointers, spot-check. GitHub renders a committed TSV as a table. column -s$'\t' -t decisions.tsv renders it in a terminal.
Composing this skill
Other skills route their audit trail here instead of inventing one. Reference it by name and let it own the format. Don't restate the columns.