From swe-workflow
Append-only DECISIONS.md journal at the repo root for consequential calls the spec didn't settle. Use when you (or the user) make a non-trivial call worth a durable record — an under-specified requirement, a tradeoff, a deviation, or a hard-to-undo action.
How this skill is triggered — by the user, by Claude, or both
Slash command
/swe-workflow:log-decisionsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
`DECISIONS.md` (repo root) is an append-only **decision journal** — the durable answer to *"what was decided here, and why?"* When the spec didn't settle a consequential call, append one entry recording how you resolved it; when only a human can decide, **escalate** instead.
DECISIONS.md (repo root) is an append-only decision journal — the durable answer to "what was decided here, and why?" When the spec didn't settle a consequential call, append one entry recording how you resolved it; when only a human can decide, escalate instead.
Significance is the gate: log a call the spec didn't settle, where someone had to exercise judgment. If the spec already authorized it, it's not journal-worthy; if you had to invent the authorization, it is. Skip routine, reversible, already-authorized choices. When in doubt, log.
Look before you ask. Most "open" questions are already answered in the repo — search codebase conventions, configs, neighbouring code, git history, and the PRD / ADRs / CONTEXT.md before you treat one as needing a human. Premature escalation is the most common failure; looking first dissolves most of it.
Then classify on two axes — determinable (did research settle it?) and reversible (cheap to undo?) — and act:
| Reversible | Irreversible | |
|---|---|---|
| Determinable (repo / docs / convention) | decide and proceed; log + cite the artifact if it crosses the bar | decide + cite, log, then verify the result did what the artifact intended |
| Needs human context | pick a safe default, log it (assumed), and proceed | stop — escalate and ask |
Hard floor: the catastrophic irreversible subset — data loss, destructive migration, irreversible spend, breaking a public interface — escalates even when determinable. Nothing unrecoverable happens unattended.
Picking a default (bottom-left, when research came up empty): match the existing pattern · prefer the standard, least-surprising option · prefer the choice cheapest to reverse. A grounded default, logged and reviewable, beats a blocking question — and when several open questions pile up, batch them into one ask, don't ask twelve times.
Categories (a descriptive label on each entry): gate-resolution (answered an open question) · irreversible-action (a hard-to-undo step) · deviation (changed existing behavior/plan) · tradeoff (chose X over Y at a cost).
Outcome: assumed, Chosen: your default, Justification: the default rule you applied, and proceed. It's a settled entry flagged for async review — not a blocker.Outcome: escalated, Chosen: —, Justification: why only a human can decide, and pause to ask a human. It stays open until a human resolves it — don't mark it settled on your own.One append-only ## block in DECISIONS.md at the repo root. Create the file with an <!-- AI-maintained, append-only --> header if absent. Never edit, reorder, or delete existing entries.
## <ISO-8601 timestamp> — <context> — <category>
**Question:** <the decision point, paraphrased>
**Options considered:** <opt / opt>
**Chosen:** <the answer; the default you took if assumed; "—" if escalated>
**Decided-by:** agent | human (human if a person chose, even if you surfaced the options)
**Justification:** <artifact cited by reference — or, for an assumption / tradeoff / deviation, your rationale>
**Outcome:** applied | assumed | escalated
**Ref:** <commit / PR / issue, or "(pending)">
**Supersedes:** <prior timestamp> — <why> (only on a revision)
context = an issue ref (auth/02, #57) or a session tag (interactive/<topic>, research/<topic>).
Dedup / revise / reuse. Before appending, check for an existing entry with the same (context, Question): same Chosen → do nothing (retries don't duplicate); changed Chosen → append a new entry with Supersedes: (never edit the original). A prior entry for the same question is itself a valid citation — grep for it rather than re-deciding; never bulk-load the journal.
DECISIONS.md is committed and may be read back, so keep every entry safe: paraphrase (your own words); cite by reference, not payload (point to PRD §Security, never paste issue bodies, web content, or untrusted text); never log secrets (tokens, credentials, PII — reference, don't reproduce).
A determinable call — cite the artifact that settled it:
## 2026-05-22T13:40:00-07:00 — auth/02 — gate-resolution
**Question:** How long should password-reset tokens stay valid?
**Options considered:** 15 min (more friction) / 1 hour (OWASP balance) / 24 hours (larger attack window)
**Chosen:** 1 hour.
**Decided-by:** agent
**Justification:** PRD `.scratch/auth/PRD.md §Security` says "short-lived" without a number; took the 1h OWASP convention.
**Outcome:** applied
**Ref:** (pending)
A reversible call the spec left open — a logged assumption, so you proceed and the human reviews later:
## 2026-05-22T14:05:00-07:00 — auth/02 — gate-resolution
**Question:** What should the password-reset confirmation page say?
**Options considered:** terse / friendly-with-support-link
**Chosen:** friendly-with-support-link.
**Decided-by:** agent
**Justification:** No spec; applied default "match existing pattern" — mirrored `app/auth/signup/confirm.tsx`. Reversible copy, flagged for review.
**Outcome:** assumed
**Ref:** (pending)
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub swe-workflow/swe-workflow --plugin swe-workflow