codenamev/ai-software-architect/create-adr

Create Architectural Decision Record (ADR)

Creates structured ADRs following the framework's template.

Process

1. Gather Context

Ask if needed:

• What decision is being made?
• What problem does it solve?
• What alternatives were considered?
• What are the trade-offs?

Then read .architecture/principles.md if it exists. The decision is written against it in step 6.

2. Generate ADR Number

# Find highest ADR number
ls .architecture/decisions/adrs/ | grep -E "^ADR-[0-9]+" | sed 's/ADR-//' | sed 's/-.*//' | sort -n | tail -1

New ADR = next sequential number (e.g., if highest is 003, create 004)

3. Validate and Sanitize Input

Security: Sanitize user input to prevent path traversal and injection:

• Remove or replace: .., /, \, null bytes, control characters
• Convert to lowercase kebab-case: spaces → hyphens, remove special chars
• Limit length: max 80 characters for filename portion
• Validate result: ensure filename contains only [a-z0-9-]

4. Create Filename

Format: ADR-XXX-kebab-case-title.md

Examples:

• ADR-001-use-react-for-frontend.md
• ADR-002-choose-postgresql-database.md

Valid input: "Use React for Frontend" → use-react-for-frontend Invalid blocked: "../etc/passwd" → sanitized or rejected

5. Check Configuration

• Read .architecture/config.yml to check if pragmatic_mode is enabled
• If enabled and applies to ADR creation, include Pragmatic Enforcer analysis

6. Write ADR

Use the template from .architecture/templates/adr-template.md:

Core sections:

• Status, Context, Decision Drivers, Decision, Consequences
• Implementation, Alternatives Considered, Validation, References

Principles check (when .architecture/principles.md exists): name each recorded principle the decision upholds under Decision Drivers, and each one it conflicts with under Consequences → Negative. A decision that conflicts with a principle is still recordable; an unacknowledged conflict is not. If the point of the decision is to change or retire a principle, say so in the first sentence of Context and edit .architecture/principles.md in the same change, citing the ADR number next to the edited principle. The two files move together or not at all.

If pragmatic_mode is enabled: Add Pragmatic Enforcer Analysis section:

• Necessity Assessment (0-10): Current need, future need, cost of waiting, evidence
• Complexity Assessment (0-10): Added complexity, maintenance, learning curve, dependencies
• Alternative Analysis: Review if simpler alternatives adequately considered
• Simpler Alternative Proposal: Concrete proposal for simpler approach
• Recommendation: Approve / Approve with simplifications / Defer / Recommend against
• Pragmatic Score: Necessity, Complexity, Ratio (target <1.5)
• Overall Assessment: Appropriate engineering vs over-engineering

If deferrals enabled: Track deferred decisions in .architecture/deferrals.md

7. Save ADR

Write to: .architecture/decisions/adrs/ADR-XXX-title.md

8. Report to User

Created ADR-XXX: [Title]
 
Location: .architecture/decisions/adrs/ADR-XXX-title.md
Status: [Status]
 
Key Points:
- Decision: [Summary]
- Main benefit: [Key benefit]
- Main trade-off: [Key trade-off]
 
Next Steps:
- [Immediate action 1]
- [Immediate action 2]

When to Create ADRs

Do create for:

• Technology choices (frameworks, databases, languages)
• Architectural patterns (microservices, event-driven, etc.)
• Infrastructure decisions (cloud provider, deployment)
• Security approaches (authentication, encryption)

Don't create for:

• Implementation details (function names, variable names)
• Temporary decisions
• Minor decisions with limited impact

Status Lifecycle

• Proposed: Documented but not approved
• Accepted: Approved and should be implemented
• Deprecated: No longer best practice
• Superseded: Replaced by newer ADR (reference it)

Related Skills

Before Creating ADR:

• "What's our architecture status?" - Check existing ADRs to avoid duplication
• "List architecture members" - See who should review the decision

After Creating ADR:

• "Ask [specialist] to review [the ADR]" - Get focused expert review
• "Start architecture review for [version]" - Include in comprehensive review

Workflow Examples:

1. Create ADR → Ask Security Specialist to review → Revise ADR
2. Architecture review → Create ADRs for key decisions → Status check

Notes

• Focus on "why" more than "what"
• Be honest about trade-offs
• Keep it concise but complete
• ADRs can be updated as new information emerges