| name | adr-management |
| description | Manage Architecture Decision Records (ADRs) for Thymian. Use this skill when asked to create, update, accept, deprecate, or supersede ADRs, document architectural decisions, or maintain the ADR index. Triggers include "create ADR", "new architectural decision", "update ADR status", "accept ADR", "deprecate ADR", "supersede ADR". |
ADR Management Skill
This skill helps manage Architecture Decision Records (ADRs) for the Thymian project following the Michael Nygard template.
File Locations
- ADR files:
docs/arc42/adr/NNNN-short-title.md
- ADR template:
docs/arc42/adr/ADR-TEMPLATE.md
- ADR index:
docs/arc42/09-architectural-decisions.md
- Quality requirements:
docs/arc42/10-quality-requirements.md
ADR Numbering
Use 4-digit zero-padded numbers (e.g., 0001, 0002, 0015). To find the next number, check the ADR index in docs/arc42/09-architectural-decisions.md and increment the highest existing number.
Status Values
- Proposed: Under discussion, not yet accepted
- Accepted: Decision has been made and is in effect
- Deprecated: No longer recommended, but not replaced
- Superseded: Replaced by another ADR (must link to successor)
Operations
Creating a New ADR
- Determine the next ADR number by checking the index in
docs/arc42/09-architectural-decisions.md
- Copy
docs/arc42/adr/ADR-TEMPLATE.md to docs/arc42/adr/NNNN-short-title.md
- Fill in all sections:
- Update the title:
# ADR-NNNN: [Title]
- Set Status to
Proposed and Date to today's date (YYYY-MM-DD)
- Write Context, Decision, and Consequences sections
- Add Related section with links to relevant quality requirements (10.2.x)
- Add an entry to the index table in
docs/arc42/09-architectural-decisions.md
- If the ADR relates to a quality requirement, update
docs/arc42/10-quality-requirements.md to add a back-reference in the "Related ADRs" column
Accepting an ADR
- Change Status from
Proposed to Accepted
- Update the Date to today's date
- Add entry to Status History table at the bottom
- Update the status in
docs/arc42/09-architectural-decisions.md index
Deprecating an ADR
- Change Status from
Accepted to Deprecated
- Update the Date to today's date
- Add a note in Consequences explaining why it's deprecated
- Add entry to Status History table
- Update the status in
docs/arc42/09-architectural-decisions.md index
Superseding an ADR
- Create the new ADR that supersedes the old one (see "Creating a New ADR")
- In the old ADR:
- Change Status to
Superseded
- Update the Date to today's date
- Fill in the "Superseded by" column with link to new ADR:
[ADR-NNNN](NNNN-title.md)
- Add entry to Status History table
- In the new ADR:
- Fill in the "Supersedes" column with link to old ADR:
[ADR-NNNN](NNNN-title.md)
- Reference the old ADR in the Related section
- Update both entries in
docs/arc42/09-architectural-decisions.md index
Cross-References (Bidirectional Linking)
ADRs must maintain bidirectional links with arc42 documentation:
ADR → Quality Requirements
In the ADR's "Related" section, link to relevant quality scenarios:
## Related
- [Quality Requirement 10.2.3](../10-quality-requirements.md#102-quality-scenarios): Modularity — Description
Quality Requirements → ADR
In docs/arc42/10-quality-requirements.md, the "Related ADRs" column should link back:
| ... | 10.2.3 | [ADR-0001](adr/0001-core-features-as-plugins.md) |
ADR → Other Arc42 Chapters
Link to relevant constraints, context, or other chapters:
- [Constraint](../02-constraints.md): Description
- [Context](../03-context-and-scope.md): Description
Validation Checklist
When creating or updating an ADR, verify:
