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

Installs 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/
60 chars · catalog description✓ has a “when” trigger
Beginner

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

You give it
Topic description and status request
You get back
Markdown file formatted according to template requirements

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.

SkillInstallsUpdatedSafetyDifficulty
decisions (this skill)47moNo flagsBeginner
project-planner321yReviewIntermediate
spec-kit-workflow1111moNo flagsIntermediate
specification-architect131yReviewAdvanced

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.

32115

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

11111

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.

1388

architecture

davila7

Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design.

1244

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.

744

planning-agent

parcadei

Planning agent that creates implementation plans and handoffs from conversation context

531

Search skills

Search the agent skills registry