create-architectural-decision-record

Create Architectural Decision Record

Create an ADR document for ${input:DecisionTitle} using structured formatting optimized for AI consumption and human readability.

Inputs

• Context: ${input:Context}
• Decision: ${input:Decision}
• Alternatives: ${input:Alternatives}
• Stakeholders: ${input:Stakeholders}

Input Validation

If any of the required inputs are not provided or cannot be determined from the conversation history, ask the user to provide the missing information before proceeding with ADR generation.

Security Constraints

The following constraints MUST be enforced before any file operation is performed.

Output Path

Always use docs/adr/ relative to the workspace root. Never construct an absolute path (no leading /). Never write outside docs/adr/.

Title Slug Sanitization

Before constructing the filename from ${input:DecisionTitle}, sanitize the title to produce a safe slug:

1. If the title contains path traversal sequences (/, \, ..) or other characters that cannot be reduced to safe lowercase alphanumeric-and-hyphen form, stop and ask the user for a valid title before proceeding.
2. Convert the title to lowercase.
3. Replace every character that is not [a-z0-9] with a hyphen (-).
4. Collapse runs of consecutive hyphens to a single hyphen and strip any leading or trailing hyphens.
5. If the resulting slug is empty or invalid, ask the user for a valid title. Do not proceed with an empty or unsafe slug.

Example: "My DB Selection (v2)!" → "my-db-selection-v2"

Sequencing

Read the existing files in docs/adr/ to determine the next NNNN value. If the directory does not exist or cannot be read, use 0001 and note this assumption in the ADR's Implementation Notes.

Requirements

• Use precise, unambiguous language
• Follow standardized ADR format with front matter
• Include both positive and negative consequences
• Document alternatives with rejection rationale
• Structure for machine parsing and human reference
• Use coded bullet points (3-4 letter codes + 3-digit numbers) for multi-item sections

The ADR must be saved in the docs/adr/ directory (relative to the workspace root — no leading slash) using the naming convention: adr-NNNN-[title-slug].md, where NNNN is the next sequential 4-digit number (e.g., adr-0001-database-selection.md).

Required Documentation Structure

The documentation file must follow the template below, ensuring that all sections are filled out appropriately. The front matter for the markdown should be structured correctly as per the example following:

---
title: "ADR-NNNN: [Decision Title]"
status: "Proposed"
date: "YYYY-MM-DD"
authors: "[Stakeholder Names/Roles]"
tags: ["architecture", "decision"]
supersedes: ""
superseded_by: ""
---

# ADR-NNNN: [Decision Title]

## Status

**Proposed** | Accepted | Rejected | Superseded | Deprecated

## Context

[Problem statement, technical constraints, business requirements, and environmental factors requiring this decision.]

## Decision

[Chosen solution with clear rationale for selection.]

## Consequences

### Positive

- **POS-001**: [Beneficial outcomes and advantages]
- **POS-002**: [Performance, maintainability, scalability improvements]
- **POS-003**: [Alignment with architectural principles]

### Negative

- **NEG-001**: [Trade-offs, limitations, drawbacks]
- **NEG-002**: [Technical debt or complexity introduced]
- **NEG-003**: [Risks and future challenges]

## Alternatives Considered

### [Alternative 1 Name]

- **ALT-001**: **Description**: [Brief technical description]
- **ALT-002**: **Rejection Reason**: [Why this option was not selected]

### [Alternative 2 Name]

- **ALT-003**: **Description**: [Brief technical description]
- **ALT-004**: **Rejection Reason**: [Why this option was not selected]

## Implementation Notes

- **IMP-001**: [Key implementation considerations]
- **IMP-002**: [Migration or rollout strategy if applicable]
- **IMP-003**: [Monitoring and success criteria]

## References

- **REF-001**: [Related ADRs]
- **REF-002**: [External documentation]
- **REF-003**: [Standards or frameworks referenced]