Documenting Decisions
Checkpoint tags
| Tag | When to mark |
|---|---|
ARCH | New abstractions, deps, data models, component boundaries — anything that shapes long-term structure. |
SCOPE | You resolved an ambiguity in the task by choosing an interpretation. |
IFACE | Changed a public API, config schema, CLI flag, env var, or wire format. |
SEC | Touched auth, crypto, permissions, network exposure, or input validation. |
IRREV | Created a migration, data deletion, deployment trigger, or external side effect. |
NOVEL | No existing repo pattern to follow — you interpolated from training data. |
Do not mark routine changes (pattern-following, boilerplate, refactoring).
Format
See this skill's references/ decision-markers.md and (if needed) marker-examples.md.
After task completion
Generate decision log from markers in changed files and add to PR description:
## Decisions requiring review
- **TAG** `file:line` — explanation
## Routine (skip review)
[One-line summary]
If an ARCH or IRREV marker meets the writing-adrs bar (hard to reverse, surprising without context, result of a real trade-off), also write the ADR per that skill.
Reconcile driving ticket
Work driven by ticket → update it before close: fold in deviations, mid-session scope, decisions above (or their ADR/glossary refs). Per to-tickets reproducibility invariant: replayed issue stream builds final state, not first draft.
Diff classification mode
When user requests review of diff, classify each hunk as one of the six tags or ROUTINE. Present as File: path — TAG with line ranges.
Reference files
references/canary-signals.md— CI scripts for automated checkpoint detection (repo setup, not runtime).references/marker-examples.md— example markers in multiple languages.- other files in references are only relevant if explicitly mentioned in AGENTS.md or requested by the user.