documenting-decisions — Claude Code skill: decisions, install
This skill marks important choices in agent-written code and turns them into a review log. Use it during planning, implementation, fixes, or diff review.
npx skills add pandoscope/skills --skill documenting-decisions -a claude-codeWhat documenting-decisions does
The skill guides the agent on where to add decision comments while it plans, implements, or fixes code. ARCH covers structural choices such as new abstractions and data models; SCOPE records how an ambiguous request was interpreted. Other markers cover public interfaces, security-sensitive changes, irreversible effects, and choices made without an existing repository pattern.
When the task ends, markers from changed files become a PR section with decisions that need human review, plus a short routine-change summary. Routine edits are deliberately left unmarked, so ordinary refactoring does not create review noise.
On request, the skill switches to diff classification and labels each hunk with a decision tag or ROUTINE, including the file and line range. An ARCH or IRREV choice can also lead to an ADR when reversing it is difficult or its trade-off needs context; the related ticket should be updated before closure.
What it helps with
- spot architectural choices in generated code
- record how an ambiguous task was resolved
- flag API, configuration, and security changes
- turn code markers into a PR decision log
- classify diff hunks during review
Example prompts for the agent
- Plan this task and mark the choices that need human review.
- Review my diff and classify every hunk with the appropriate decision tag.
- After implementation, build the PR decision log and update the related ticket.
How to install documenting-decisions
1Skills CLI (Vercel)
npx skills add pandoscope/skills --skill documenting-decisions -a claude-code2Manually: put the files in place
~/.claude/skills/documenting-decisions/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/documenting-decisions/
1Skills CLI (Vercel)
npx skills add pandoscope/skills --skill documenting-decisions -a codex2Manually: put the files in place
.agents/skills/documenting-decisions/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pandoscope/skills --skill documenting-decisions -a cursor2Manually: put the files in place
.cursor/skills/documenting-decisions/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pandoscope/skills documenting-decisions2Manually: put the files in place
.github/skills/documenting-decisions/SKILL.md1Skills CLI (Vercel)
npx skills add pandoscope/skills --skill documenting-decisions -a gemini-cli2Platform CLI
gemini skills install https://github.com/pandoscope/skills --path original/documenting-decisionsManually: put the files in place
.devin/skills/documenting-decisions/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pandoscope/skills --skill documenting-decisions -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about documenting-decisions
How do I install documenting-decisions in Claude Code?
Run npx skills add pandoscope/skills --skill documenting-decisions -a claude-code, then check ~/.claude/skills/documenting-decisions/SKILL.md.
What does documenting-decisions do?
It marks consequential choices in code comments and gathers them into a PR review log. On request, it also classifies diff hunks by decision type.
Which platforms support documenting-decisions?
The skill supports Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode.
Source text
SKILL.md · MIT
--- 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. --- # 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.
© pandoscope · MIT · pandoscope/skills
