decisions
Guides the creation and management of ADR and PDR documents.
Install
mkdir -p .claude/skills/decisions && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/1571" && unzip -o skill.zip -d .claude/skills/decisions && rm skill.zipInstalls to .claude/skills/decisions
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Use when creating or editing ADRs or PDRs in docs/decisions/Key capabilities
- →Verify template adherence
- →Assign sequential IDs (NNN)
- →Validate date formatting against git log
- →Enforce status state transitions
How it works
Validates file content against mandatory templates and enforces strict naming and linking conventions within the decision directory.
Inputs & outputs
When to use decisions
- →Create new ADR
- →Document architecture choices
- →Update decision status
About this skill
Decision Records
Procedural knowledge for creating ADRs (Architecture Decision Records) and PDRs (Product Decision
Records) in docs/decisions/.
Templates
MANDATORY: Read the relevant template before creating or editing ANY decision document.
- ADR template:
docs/decisions/architecture/TEMPLATE.md - PDR template:
docs/decisions/product/TEMPLATE.md
Rules
Records carry no status. Every record on master is in force; Git history is the full record of
past versions.
One decision per record. Do not bundle multiple decisions into a single ADR/PDR. State each rule once, in the record that owns it, and link to it from other records instead of restating it.
Criteria, not inventories. State the rule or criterion that decides each case. MUST NOT enumerate the current cases, types, values, or members it covers; that list changes with ordinary features and fixes and belongs in code. Label any example as an example.
Naming: NNN-kebab-case-title.md, sequential per category. MUST NOT reuse a number, including
numbers of deleted records; check git log --diff-filter=D --name-only -- docs/decisions/ when the
highest number may have been deleted.
Body is the current decision. Write every section as if the decision was always this way. MUST NOT add amendment prose ("previously", "updated to", "originally"), superseded options presented as history, or "Status" lines. Former choices that a reader could propose again belong in Rejected Options.
History: one line per decision change, oldest first: - YYYY-MM-DD: {what changed}. The first
line records the original decision. Edits that do not change the decision (typos, links,
formatting, wording) get no line.
Date accuracy: Use the date the decision was made or changed, not when documented. For existing
decisions, verify against git history (git log --format="%ai" <commit> -1).
Changing a Decision
- Decision modified: rewrite the affected sections in place and append a History line. Rename the file and title when the old title no longer describes the decision; keep the number.
- Decision replaced by a different approach: rewrite the same record to the new decision.
- Decision dropped with no replacement: delete the record and update every reference to it
(
rg -n 'ADR-NNN|NNN-' docs src tests .opencode AGENTS.md).
Reference-style links: Use reference-style links for long URLs to respect line length limits:
- **Upstream:** [Discord DM][upstream] with TRaSH Guides contributor
[upstream]: https://discordapp.com/channels/@me/...
When to Create
ADR - Implementation choices, patterns, internal tradeoffs:
- Choosing between implementation approaches
- Establishing patterns affecting multiple components
- Making tradeoffs with long-term maintenance implications
PDR - Upstream changes, feature scope, external drivers:
- Responding to upstream schema or API changes
- Deciding feature scope or priorities
- Tracking external decisions that drive Recyclarr development
PDRs MUST have upstream: linking to the external driver. Private links (DMs, gated channels) are
acceptable; the link provides provenance even if not publicly accessible. If no upstream link is
available, ask the user for one before finalizing the PDR.
Attribution
No individual names in PDR body. Use roles ("TRaSH Guides contributor", "upstream maintainer") rather than personal names. Reasons:
- Roles outlast individuals
- Reduces friction in candid discussions
- Avoids taking statements out of context
Upstream link is the audit trail. The link provides who/when/full-context; the PDR body provides what/why synthesis. If someone questions a decision and cannot access the link, the PDR rationale SHOULD stand on its own merits.
Private links are valid. Discord DMs, private channels, or gated sources are acceptable upstream references. The link serves as:
- Provenance for those with access
- Good faith signal that a source exists
- Future-proofing if access later expands
Perspective
TRaSH Guides is the authoritative upstream; Recyclarr is a downstream consumer. PDRs document Recyclarr's response to guide decisions. Focus on:
- Recyclarr implementation impact
- User experience improvements
- TRaSH Guides maintainer/contributor benefits (upstream health benefits all consumers)
Exclude references to other sync tools - they're peers responding to the same upstream, not relevant to Recyclarr's decisions.
When not to use it
- →General architectural documentation
- →Writing meeting notes
Limitations
- →Requires strict naming adherence
- →One decision per record rule is mandatory
How it compares
It treats architecture decisions as version-controlled data rather than free-form prose.
Compared to similar skills
decisions side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| decisions (this skill) | 4 | 7mo | No flags | Beginner |
| project-planner | 32 | 1y | Review | Intermediate |
| spec-kit-workflow | 11 | 11mo | No flags | Intermediate |
| specification-architect | 13 | 1y | Review | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
project-planner
adrianpuiu
Comprehensive project planning and documentation generator for software projects. Creates structured requirements documents, system design documents, and task breakdown plans with implementation tracking. Use when starting a new project, defining specifications, creating technical designs, or breaking down complex systems into implementable tasks. Supports user story format, acceptance criteria, component design, API specifications, and hierarchical task decomposition with requirement traceability.
spec-kit-workflow
jmanhype
Guides specification-driven development workflow. Automatically invoked when discussing new features, specifications, technical planning, or implementation tasks. Ensures proper workflow phases (specify → clarify → plan → checklist → tasks → analyze → implement).
specification-architect
adrianpuiu
A rigorous, traceability-first system that generates five interconnected architectural documents (blueprint.md, requirements.md, design.md, tasks.md, and validation.md) with complete requirements-to-implementation traceability. Use this skill when users need to architect systems, create technical specifications, or develop structured project documentation with guaranteed traceability.
architecture
davila7
Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design.
context-driven-development
wshobson
Use this skill when working with Conductor's context-driven development methodology, managing project context artifacts, or understanding the relationship between product.md, tech-stack.md, and workflow.md files.
planning-agent
parcadei
Planning agent that creates implementation plans and handoffs from conversation context