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

One decision per record. Do not bundle multiple decisions into a single ADR/PDR. Each decision should be independently trackable, referenceable, and supersedable.

Naming: NNN-kebab-case-title.md (sequential per category)

Date accuracy: Use the date the decision was made, not when documented. For existing decisions, verify against git history (git log --format="%ai" <commit> -1).

Status Values

• proposed - Under consideration, not yet decided
• accepted - Decision made and finalized
• deprecated - No longer applies (context changed)
• superseded by {ADR,PDR}-NNN - Replaced by another decision

For accepted decisions with pending implementation details, use accepted and note the pending aspects in the document body.

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 require upstream: frontmatter linking to the external driver (issue, PR, Discord thread).

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.