ADR write guide

[cableman]

Title: A brief document title, e.g., “001: Decision to Choose a Cloud Provider for Data Project.”
Created By: Indicate the creator if the wiki doesn’t provide details.
Date: The creation date of the ADR.
Decision Maker: The person(s) responsible for making the decision.
Stakeholders: Those offering advice and those affected by the decision.
Status: The status of the ADR (Draft, Accepted, Rejected, Deprecated by YYY, Supersedes XXX).
Context: This section highlights the problem statement, drivers (functional and non-functional), and options considered.
Decision: Document the chosen decision and its rationale.
Consequences: Detail the resulting context or state after implementing the decision, including trade-offs.

[yepzdk]

Plan: ADR Writing Skill Implementation

Based on the issue requirements and existing skill architecture, here's the plan for implementing the ADR skill.

---

1. File Creation

Create /skills/itkdev-adr.md with YAML frontmatter:

---
name: itkdev-adr
description: Use when creating, updating, or managing Architecture Decision Records (ADRs), documenting architectural decisions, or when discussion reveals a significant technical decision that should be recorded.
---

---

2. Skill Content Structure

The skill should guide Claude through the full ADR lifecycle with the following sections:

A. ADR Format Template

Define the canonical ADR structure based on the issue requirements:

• Title: Format as NNN: Brief Decision Title (e.g., "001: Decision to Choose PostgreSQL")
• Metadata Header: Created By, Date, Decision Maker, Stakeholders
• Status: Draft → Accepted/Rejected → Deprecated by YYY / Supersedes XXX
• Context: Problem statement, drivers (functional/non-functional), options considered
• Decision: Chosen option and rationale
• Consequences: Trade-offs, resulting state, follow-up actions

B. When to Create an ADR

Clear criteria for when ADRs are needed:

• Technology/framework selection
• Architectural pattern choices
• Integration approach decisions
• Security-related decisions
• Breaking changes or deprecations
• Cross-team impacting decisions

C. ADR Workflow Phases

Phase 1: Draft Creation

• Detect decision need from conversation/issue
• Generate next ADR number (scan existing ADRs)
• Create file in docs/adr/ or project-specific location
• Populate template with initial context

Phase 2: Collaborative Refinement

• Help articulate options and trade-offs
• Ensure all stakeholders are identified
• Validate context completeness

Phase 3: Decision & Approval

• Guide through decision rationale documentation
• Update status from Draft to Accepted/Rejected
• Link to related issues/PRs

Phase 4: Maintenance

• Handle deprecation (status update, link to superseding ADR)
• Create new ADR when superseding existing ones

D. File Organization Standards

• Location: docs/adr/ (configurable per project)
• Naming: NNN-brief-title.md (e.g., 001-database-selection.md)
• Index: Maintain docs/adr/README.md with ADR listing

E. Integration Points

• Link to GitHub issues when ADR relates to implementation
• Follow itkdev-github-guidelines for commits/PRs when creating ADRs
• Support for both new project setup and existing projects

---

3. Example ADR Template (to include in skill)

# NNN: [Decision Title]

| Field | Value |
|-------|-------|
| **Created By** | [Author Name] |
| **Date** | YYYY-MM-DD |
| **Decision Maker** | [Name(s)] |
| **Stakeholders** | [Advisors and affected parties] |
| **Status** | Draft / Accepted / Rejected / Deprecated by [NNN] / Supersedes [NNN] |

## Context

[Problem statement and background]

### Drivers
- **Functional:** [Requirements that influence the decision]
- **Non-functional:** [Quality attributes: performance, security, maintainability]

### Options Considered
1. **Option A**: [Description]
2. **Option B**: [Description]
3. **Option C**: [Description]

## Decision

[Chosen option and detailed rationale]

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]

### Negative / Trade-offs
- [Trade-off 1]
- [Trade-off 2]

### Follow-up Actions
- [ ] [Action item if any]

---

4. Implementation Steps

• Step 1: Create skills/itkdev-adr.md with frontmatter and content structure
• Step 2: Include the full ADR template with all required fields
• Step 3: Add workflow guidance for each phase (draft → accepted → maintenance)
• Step 4: Add criteria section for "when to write an ADR"
• Step 5: Document file organization standards (location, naming, indexing)
• Step 6: Test skill activation with relevant prompts
• Step 7: Update CHANGELOG.md following Keep a Changelog format

---

5. Success Criteria

• Skill activates when user mentions ADRs, architectural decisions, or decision documentation
• Claude can create properly formatted ADRs following the template
• Claude can update existing ADR status (deprecate, supersede)
• Claude maintains ADR index if present
• Skill integrates smoothly with existing GitHub workflow skills

---

Let me know if you'd like any adjustments to this plan before implementation!

[yepzdk]

@cableman is the ADR format you used, based on a format that is documented elsewere?