# Develop Adr

> Creates an Architecture Decision Record following the Nygard format to document significant technical decisions, their context, and consequences. Use when making technical choices that affect system architecture, technology selection, or development patterns.

- **Type:** Skill
- **Install:** `agentstack add skill-product-on-purpose-pm-skills-develop-adr`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [product-on-purpose](https://agentstack.voostack.com/s/product-on-purpose)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [product-on-purpose](https://github.com/product-on-purpose)
- **Source:** https://github.com/product-on-purpose/pm-skills/tree/main/skills/develop-adr
- **Website:** https://product-on-purpose.github.io/pm-skills/

## Install

```sh
agentstack add skill-product-on-purpose-pm-skills-develop-adr
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Architecture Decision Record (ADR)

An Architecture Decision Record documents a significant technical decision along with its context and consequences. ADRs capture the "why" behind architectural choices so future team members understand the reasoning - especially important when they question why something was done a particular way. This skill follows Michael Nygard's lightweight ADR format.

## When to Use

- Making significant technical decisions that affect system architecture
- Choosing between technology options (frameworks, databases, services)
- Establishing patterns that future development should follow
- Documenting the rationale for constraints or non-obvious approaches
- Preserving institutional knowledge about past decisions

## When NOT to Use

- The decision is a product or UX design choice, not architecture or technology -> use `develop-design-rationale`
- You are still exploring whether an approach is feasible -> time-box the exploration and record it with `develop-spike-summary` first
- You need to pitch a solution to stakeholders -> use `develop-solution-brief`; an ADR records a decision, it does not sell one
- Nothing is actually being decided (the status quo continues unchanged): an ADR without a decision is noise; wait until there is one

## Instructions

When asked to create an ADR, follow these steps:

1. **Assign a Number and Title**
   ADRs are numbered sequentially (ADR-001, ADR-002, etc.) for easy reference. The title should be a short noun phrase describing the decision, like "Use PostgreSQL for order data" or "Adopt React for frontend."

2. **Set the Status**
   New ADRs start as "Proposed." After team review, they become "Accepted," "Deprecated," or "Superseded by ADR-XXX." Status changes should be tracked.

3. **Describe the Context**
   Explain the circumstances that led to this decision. What problem are you solving? What forces are at play (technical constraints, team expertise, timeline, cost)? This section should help a reader who wasn't there understand why this decision was needed.

4. **State the Decision**
   Clearly articulate what you decided. Use active voice: "We will use..." rather than "It was decided..." Be specific about what is and isn't included in the decision.

5. **Document the Consequences**
   List the outcomes of this decision - positive, negative, and neutral. Good ADRs are honest about trade-offs. What becomes easier? What becomes harder? What new constraints or options does this create?

## Output Format

Use the template in `references/TEMPLATE.md` to structure the output. A complete ADR fills every template section: Status; Context; Decision; Consequences; Alternatives Considered; and References.

## Quality Checklist

Before finalizing, verify:

- [ ] Title is a short, descriptive noun phrase
- [ ] Status is clearly indicated (Proposed/Accepted/Deprecated/Superseded)
- [ ] Context explains why this decision was needed
- [ ] Decision is stated clearly in active voice
- [ ] Consequences include both positive and negative outcomes
- [ ] ADR can stand alone without requiring other documents

## Examples

See `references/EXAMPLE.md` for a completed example.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [product-on-purpose](https://github.com/product-on-purpose)
- **Source:** [product-on-purpose/pm-skills](https://github.com/product-on-purpose/pm-skills)
- **License:** Apache-2.0
- **Homepage:** https://product-on-purpose.github.io/pm-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-product-on-purpose-pm-skills-develop-adr
- Seller: https://agentstack.voostack.com/s/product-on-purpose
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.