Documentation · Agent Development / AGENT SKILL

documenting-decisions

1.8K installs 1 GitHub stars

Mark significant decisions in agent-generated code for human attention and review.
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.

One new superpower.

Run this command in your project to choose an agent and install the skill.

npx skillycli add https://github.com/pandoscope/skills --skill documenting-decisionsView original source

BEFORE YOU INSTALL

Understand the trade-offs.

SECURITY REVIEW

Not yet assessed

Review the original instructions and requested permissions before installing.

No security review is available for this catalog entry yet.

SKILL QUALITY

Not yet assessed

How clearly the skill guides your agent, how complete its workflow is, and how you can check the outcome.

No quality assessment is available for this catalog entry yet.

The full skill.

Original instructions from the publisher’s SKILL.md

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