# Decision Trail

> Records and audits a branch's decision trail — what was decided, why, and the evidence. Use to track or review rationale.

- Skill: `gpu-cli/decision-trail` (Agent Skill, multi-file: 25 files)
- Install (CLI): `npx skillmds@latest add gpu-cli/decision-trail`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gpu-cli/decision-trail/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gpu-cli (https://skillmd.com/u/gpu-cli)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/gpu-cli/decision-trail

---


# Decision Trail

Keep one reviewable, append-only decision trail for a branch worked by people
and agents. The trail records what was decided, why, perceived confidence,
evidence, and outcome. It uses `bd` when available and falls back to TSV.

Use one command namespace:

```text
/decision-trail <command> [arguments]
```

| Command | Use for | Read |
| --- | --- | --- |
| `toggle [on|off] [branch]` | Start or stop tracking for a branch | [references/toggle.md](references/toggle.md) |
| `track "<decision> because <why>" [--confidence high|medium|low]` | Record or enrich a decision | [references/track.md](references/track.md) |
| `show [branch] [--pr]` | Render, validate, and optionally publish a trail to its PR | [references/show.md](references/show.md) |

Route the first argument to its reference. With no argument, show this command
table and ask which operation is wanted. Treat an unrecognized argument as a
request to show the current branch's trail.

## Shared runtime

All helpers live in `.agents/skills/decision-trail/`. Read
[references/config-schema.md](references/config-schema.md) only when changing
tracking configuration, and [references/row-format.md](references/row-format.md)
only when changing row semantics. Run the relevant helper rather than manually
editing `.decision-trail/` state.

`toggle on` materializes a committed `.decision-trail/` runtime and configures
Git's relative `core.hooksPath`. Tell the user to commit `.decision-trail/`
after enabling it.
The optional Claude Code Stop hook enriches meaningful commit stubs; the Git
post-commit hook captures the stubs regardless.

## Validation

Run `bash tests/selftest.sh` after changing the bundled runtime.