ADR Management Skill

Manage Architectural Decision Records (ADRs) stored in doc/adr/ directory.

Purpose

Provide structured management of architectural decisions:

Create ADRs with automatic numbering and template
Read ADR content by number
Update ADR status through lifecycle
Delete ADRs when necessary
List all ADRs with optional filtering
Validate ADR format using ref-documentation

Available Workflows

| Workflow | Purpose | Script Used | |----------|---------|-------------| | list-adrs | List all ADRs with optional filtering | manage-adr.py list | | create-adr | Create new ADR from template | manage-adr.py create | | read-adr | Read ADR content | manage-adr.py read | | update-adr | Update ADR status | manage-adr.py update | | delete-adr | Delete ADR (with confirmation) | manage-adr.py delete | | validate-adr | Validate ADR format | ref-documentation workflows |

Workflow: list-adrs

List all ADRs with optional status filtering.

Parameters

status (optional): Filter by status (Proposed, Accepted, Deprecated, Superseded)

Steps

Step 1: Execute List

python3 .plan/execute-script.py pm-documents:manage-adr:manage-adr list [--status {status}]

Step 3: Parse Output

Parse JSON output containing ADR list with metadata.

Output

{
  "success": true,
  "operation": "list",
  "count": 3,
  "adrs": [
    {"number": 1, "title": "Use PostgreSQL", "status": "Accepted", "path": "doc/adr/001-Use_PostgreSQL.adoc"},
    {"number": 2, "title": "Adopt Quarkus", "status": "Proposed", "path": "doc/adr/002-Adopt_Quarkus.adoc"}
  ]
}

Workflow: create-adr

Create a new ADR with automatic numbering.

Parameters

title (required): ADR title
status (optional, default: "Proposed"): Initial status

Steps

Step 1: Create ADR

python3 .plan/execute-script.py pm-documents:manage-adr:manage-adr create --title "{title}" [--status "{status}"]

Step 3: Parse Output

Extract created file path from JSON output.

Step 4: Open for Editing

Read the created file and inform user to fill in content sections.

Step 5: Validate Format

Skill: pm-documents:ref-documentation
Execute workflow: validate-format
Parameters:
  target: {created_path}

Output

ADR Created: doc/adr/004-{title}.adoc
Number: ADR-004
Status: Proposed

Next steps:
1. Edit doc/adr/004-{title}.adoc to fill in:
   - Context
   - Decision
   - Consequences
   - Alternatives
2. Update status to "Accepted" when approved

Workflow: read-adr

Read ADR content by number.

Parameters

number (required): ADR number (1, 2, 3, etc.)

Steps

Step 1: Read ADR

python3 .plan/execute-script.py pm-documents:manage-adr:manage-adr read --number {number}

Step 3: Display Content

Show ADR metadata and content to user.

Workflow: update-adr

Update ADR status through lifecycle.

Parameters

number (required): ADR number
status (required): New status (Proposed, Accepted, Deprecated, Superseded)

Steps

Step 1: Update ADR

python3 .plan/execute-script.py pm-documents:manage-adr:manage-adr update --number {number} --status {status}

Step 3: Confirm Update

Report updated status to user.

Workflow: delete-adr

Delete ADR with confirmation.

Parameters

number (required): ADR number
force (required): Must be true to confirm deletion

Steps

Step 1: Delete ADR

python3 .plan/execute-script.py pm-documents:manage-adr:manage-adr delete --number {number} --force

Step 3: Confirm Deletion

Report deletion to user.

Workflow: validate-adr

Validate ADR format using ref-documentation skill.

Parameters

number (required): ADR number to validate

Steps

Step 1: Find ADR Path

Use list-adrs workflow to get ADR path by number.

Step 2: Validate Format

Skill: pm-documents:ref-documentation
Execute workflow: validate-format
Parameters:
  target: {adr_path}

Step 3: Report Results

Report validation results to user.

Integration with ref-documentation

This skill integrates with ref-documentation for:

Format validation: Ensures AsciiDoc formatting compliance
Link verification: Validates cross-references
Content review: Reviews ADR content quality

ADR Lifecycle

Proposed → Accepted → [Deprecated | Superseded]

| Status | Meaning | |--------|---------| | Proposed | Under discussion, not yet approved | | Accepted | Approved and active | | Deprecated | No longer relevant or applicable | | Superseded | Replaced by another ADR |

ADR Template Structure

Each ADR contains these sections:

Status - Current lifecycle status
Context - Problem context and background
Decision - The architectural decision made
Consequences - Positive, negative outcomes and risks
Alternatives Considered - Options that were not chosen
References - Related documents and links

File Naming Convention

ADRs follow this naming pattern:

doc/adr/{NNN}-{Title_With_Underscores}.adoc

Examples:

doc/adr/001-Use_PostgreSQL_for_Persistence.adoc
doc/adr/002-Adopt_Quarkus_Framework.adoc
doc/adr/003-Implement_CQRS_Pattern.adoc

References

ref-documentation SKILL - Format validation