# Document Architecture Decisions

Teams lose the reasons behind important technical choices, which causes repeated debates and inconsistent implementation. This skill creates structured ADRs with context, decisions, consequences, alternatives, and review guidance.

## Install

```bash
npx skillstore add ai agent hub/ariegoldkin-architecture-decision-record
```

## Metadata

- - Slug: ariegoldkin-architecture-decision-record
- - Version: 1.0.0
- - Author: AI Agent Hub
- - GitHub username: ArieGoldkin
- - License: MIT
- - Repository: https://github.com/ArieGoldkin/ai-agent-hub/tree/main/skills/architecture-decision-record
- - Ref: main
- - Supported tools: Claude, Codex, Claude Code
- - Risk level: safe
- - Quality score: 80
- - Quality tier: silver
- - Public page: https://skillstore.pages.dev/skills/ariegoldkin-architecture-decision-record
- - Manifest: https://skillstore.pages.dev/api/skills/ariegoldkin-architecture-decision-record/manifest

## Capabilities

- Drafts ADRs using context, decision, consequences, alternatives, and references sections.
- Provides complete examples for microservices, database selection, and API versioning decisions.
- Supplies YAML frontmatter fields for ADR metadata and lifecycle tracking.
- Guides review with checklists for quality, stakeholder approval, and rejection criteria.
- Helps compare alternatives with clear pros, cons, and rejection rationale.
- Tracks ADR status values such as proposed, accepted, superseded, deprecated, and rejected.

## Use Cases

- Record major platform decisions: Document why a team chose a database, API style, deployment model, or service boundary.
- Preserve decision history: Give new team members a clear record of past decisions, alternatives, ownership, and trade-offs.
- Prepare decisions for review: Use checklists to confirm an ADR has context, consequences, realistic alternatives, and stakeholder approval.

## Prompt Templates

### Draft a basic ADR

```
Create an ADR for choosing PostgreSQL as our primary database. Include context, decision, consequences, alternatives, and references.
```

### Compare architecture options

```
Write an ADR comparing a modular monolith, microservices, and serverless architecture. Recommend one option and explain rejected alternatives.
```

### Review an existing ADR

```
Review this ADR for missing context, unclear decision language, weak alternatives, incomplete consequences, and stakeholder approval gaps.
```

### Create an ADR program

```
Design an ADR process for our engineering organization. Include status lifecycle, numbering, storage location, review roles, and superseding rules.
```

## Limitations

- Does not execute commands, inspect repositories, or create files automatically.
- Does not replace architecture review by qualified technical stakeholders.
- Does not validate cost, performance, or compliance claims against live systems.
- Does not provide diagram generation or integration with project management tools.

## Best Practices

- Write the decision in clear present-tense language with named owners and expected timing.
- Include at least two realistic alternatives with balanced pros, cons, and rejection reasons.
- Keep accepted ADRs stable and create a new ADR when a decision is superseded.

## Anti Patterns

- Writing implementation instructions instead of documenting the architectural decision and rationale.
- Listing only benefits while hiding operational, cost, security, or maintenance trade-offs.
- Using weak alternatives that were never seriously considered by the team.

## Security Audit

- - Safe to publish: true
- - Audited at: 2026-06-28T10:37:15.857\+00:00
- - Summary: The static analyzer reported command execution, network, credential, and weak-crypto indicators, but review found documentation-only Markdown. The flagged locations are template paths, code spans, example URLs, and architecture terms, with no scripts, network calls, credential access, or prompt injection found.

## Stats

- - Views: 260
- - Downloads: 5
- - Favorites: 0
- - Popularity score: 0