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: 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]

ADR Template Structure

Each ADR contains these sections:

1. Status - Current lifecycle status
2. Context - Problem context and background
3. Decision - The architectural decision made
4. Consequences - Positive, negative outcomes and risks
5. Alternatives Considered - Options that were not chosen
6. 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