craft-trail
Keep a reviewable decision trail for long or unattended work: TSV log per decision, end audit, cross-model attention flags. Use for runs a human reviews after stepping away.
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- craft-trail
- description
- Keep a reviewable decision trail for long or unattended work: TSV log per decision, end audit, cross-model attention flags. Use for runs a human reviews after stepping away.
02 资源文件 3
- 参考文档agents/openai.yaml89 B
- 参考文档CREDITS.md965 B
- 脚本scripts/log.sh1018 B
03 SKILL.md 正文
Show me your work
Keep one canonical decision trail for long-running or unattended work: a TSV log, one row per decision (what, why, evidence, result). Commit it only when a reviewer needs the trail to trust the result. Other skills route their audit trail here instead of inventing one: reference it by name and let it own the format.
Format
One TSV file, single-line cells, evidence as pointer never prose. Header:
ts phase decision why evidence result
Columns: ts is an ISO8601 timestamp; phase the phase or workstream; decision what was chosen or done, one line; craft-why the reason in plain words, a driving principle stated plainly never as a jargon tag; evidence a pointer that proves it (commit SHA, PR number, file:line, artifact or screenshot path); result the outcome or predicate state (tests green, reverted, pixel-diff 0, INCONCLUSIVE, open).
Plain-spoken rows, so a reviewer reads the trail at a glance:
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-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
Log decision points and checkpoints, not every action: a fork chosen, a unit completed with its verification, a pivot or revert with its trigger, a blocker surfaced, a gate fixed. Per loop iteration, one row. Skip the trivial and self-evident. Append-only: a wrong call gets a superseding row, history never edits or deletes. Quote cells starting with =, +, -, @ (formula injection). Plain words, no AI speak; review-unslop applies to log text too. Prefer evidence produced by committed scripts over hand-made one-offs (rule 13).
Use scripts/log.sh <logfile> <phase> <decision> <why> <evidence> <result> (stamps ts, writes the header on first use, guards the formula bytes, creates parent dirs). Bare printf appending works when the helper is out of reach, with the same guards.
A run is one conversation including later turns. A pickup, replacement agent, or new chat starts a new run: its first row carries phase start naming the ts range of prior rows it did not write, with evidence naming this run (such as its agent id). A run returning to the log first reads the tail to see whether another run wrote since; its first row after another run's start row is a start row too. Use phase start for nothing else.
Location: decisions.tsv in the work dir (.scratch/whips/<run>/decisions.tsv for whips runs), or .audit/<task-slug>.tsv for parallel efforts, out of git by default. Commit only ambitious trails a reviewer must read to trust. The full create/read map lives in docs/agents/docs-layout.md (written by /setup-repo).
Audit before handing back
Read this run's transcript from the harness transcript store, never another workspace's private chats, and walk this run's rows against what actually happened: a stretch runs from one of this run's start rows, or from the first row if this run created the log, to the next start row of another run. Every row maps to a real decision or action, each evidence resolves and shows what the row claims, unlogged forks or pivots get added as gaps. Correct the log, not the story: wrong rows are superseded, never edited, even invented ones. Rows outside this run's stretches are not audited here; when this run's own work shows one of them is wrong, supersede it like any wrong call.
Attention section
Before handing back, check every row's evidence pointer resolves and shows what the row claims. Flag only missing or weak verification evidence: rows that name no command, no output, and no captured artifact. Point at the row and name the missing proof. "No flags" is valid; subjective taste or style is out of scope here.
Read a trail top to bottom following evidence pointers (column -s$'\t' -t renders it in a terminal; hosted git renders committed TSV as a table).
04 同仓库更多 Skills
whips
Route any non-trivial task through one entry: match a playbook, drive HIT skills plus subagents, open a reviewed ready PR with ship-pr-shaped evidence.
verify-upkeep
Periodic upkeep for a project's verification skill: source wave plus live pass per feature, at most one PR of proven corrections. Use to audit the verify skill.
verify-statechart
Check a TLA+ model of a system that moves between states, such as a product flow, a protocol, or a service, and draw it as a Mermaid statechart. The report gives the shortest path to each state that breaks a rule. Use to show a bug as a path through states.
verify-new
Generate a project-local skill that drives the app like a user (launch, doctor, drive, evidence, feature map), proven once. Use when a project has no scripted proof.
ship-triage
Move issues and external PRs through a state machine of triage roles, categorise, verify, interview if needed, and write agent-ready briefs.
ship-runner
Run ready-for-agent issue queues on any schedule through /whips intake, one fresh worktree each, landing per risk tier, with the agent and model you pick at setup.