documenting-decisions

---
name: documenting-decisions
description: Routes human attention to decisions that matter in agent-generated code. Active during planning, implementing, fixing. Defines when and how to place DECISION markers in code comments. Also applies when reviewing a diff/PR on request.
license: MIT
---

# 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:

```markdown
## 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.