/skill

Architecture Decision Records

Original skill by ECC. Credit belongs to the original author.

An Architecture Decision Record, or ADR, is a short file about one key software design choice. It explains what was chosen and why.

Keep ADR files with the code. Do not leave key choices only in chat, pull request notes, or memory.

When to Use This Skill

Use this skill when:

• The user asks to record a choice or create an ADR.
• The team picks a framework, library, data store, API style, or design pattern.
• The user says, "We chose X."
• The user explains why X was picked instead of Y.
• The user asks why an old choice was made.
• A plan includes a major design tradeoff.

Do not make an ADR for small choices such as names, code style, or file layout unless they affect many parts of the system.

When a key choice appears during normal work, offer to draft an ADR. Do not create or change files without clear user approval.

ADR Format

Use this format:

# ADR-NNNN: [Short decision title]

**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by [ADR-NNNN](NNNN-title.md)
**Deciders**: [Names, roles, team, or "Unknown"]

## Context

What problem led to this choice?

[Use 2 to 5 short sentences. State the need, limits, and key facts.]

## Decision

What did the team choose?

[Use 1 to 3 clear sentences. Say what will change or be used.]

## Alternatives Considered

### [Option name]

- **Pros**: [Main gains]
- **Cons**: [Main costs]
- **Why not**: [Clear reason this option was not chosen]

### [Option name]

- **Pros**: [Main gains]
- **Cons**: [Main costs]
- **Why not**: [Clear reason this option was not chosen]

## Consequences

What becomes easier or harder?

### Positive

- [Good result]
- [Good result]

### Negative

- [Cost or tradeoff]
- [Cost or tradeoff]

### Risks

- [Risk and how the team will lower it]

Remove empty list items before saving. If a fact is not known, write Unknown or Not discussed. Never make up facts.

Create a New ADR

Follow these steps:

1. Find the main choice.
2. Gather the reason, limits, options, tradeoffs, and risks from the user and project files.
3. Ask a short question only when a missing fact could change the meaning of the ADR.
4. Check whether docs/adr/ exists.
5. If the folder does not exist, ask before creating:
   • docs/adr/
   • docs/adr/README.md
   • docs/adr/template.md
6. Find all files that start with four digits. Use the highest number plus one. Do not fill old number gaps.
7. Use a short file name such as 0004-use-redis-for-cache.md. Use lowercase words, digits, and hyphens.
8. Show the full draft to the user.
9. Write the ADR only after the user clearly approves it.
10. Add or update its row in docs/adr/README.md.
11. Check that the file link, title, date, and status match the ADR.

If the user rejects the draft, do not write any file.

If the next number may have been taken by another change, scan the folder again just before writing.

Read an Existing ADR

When the user asks why a choice was made:

1. Check for docs/adr/.
2. If it is missing, say: "I found no ADRs in this project. Would you like to start recording design choices?"
3. Check docs/adr/README.md.
4. Search ADR file names and text if the index is missing, old, or incomplete.
5. Read each likely match.
6. Report the decision, reason, status, and key tradeoffs.
7. Name the ADR file used as the source.
8. If more than one ADR matches, show the matches and ask which one the user means.
9. If no ADR matches, say: "I found no ADR for that choice. Would you like me to draft one?"

Do not treat an old ADR as active when its status is deprecated or superseded.

ADR Folder Layout

docs/
└── adr/
    ├── README.md
    ├── 0001-use-nextjs.md
    ├── 0002-use-postgresql.md
    ├── 0003-use-rest-api.md
    └── template.md

ADR Index Format

# Architecture Decision Records

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | Use Next.js for the web app | accepted | 2026-01-15 |
| [0002](0002-use-postgresql.md) | Use PostgreSQL as the main data store | accepted | 2026-01-20 |
| [0003](0003-use-rest-api.md) | Use REST for the public API | accepted | 2026-02-01 |

Keep one row per ADR. Sort rows by ADR number.

If the index is missing but ADR files exist, offer to rebuild it. Ask for approval before writing it.

Decision Signals

Clear signals include:

• "Let's use X."
• "We should use X instead of Y."
• "This tradeoff is worth it because..."
• "Record this as an ADR."
• "Why did we choose X?"

Less clear signals include:

• Two tools are compared and one is picked.
• A data model is chosen for a stated reason.
• A monolith or service-based design is chosen.
• REST or GraphQL is chosen.
• An identity or access plan is chosen.
• A hosting plan is chosen after other options are checked.

For less clear signals, ask whether the user wants an ADR draft. Do not create one on your own.

Good ADR Rules

Do:

• Name the exact choice. Write "Use Prisma" instead of "Use a database tool."
• State the reason in plain words.
• Include the options that were truly discussed.
• State both gains and costs.
• Keep the ADR short enough to read in about two minutes.
• Use present tense, such as "We use PostgreSQL."
• Link related ADRs when useful.
• Mark guesses and missing facts.

Do not:

• Record small code choices.
• Write a long essay.
• Invent options that were never discussed.
• Hide costs or risks.
• Change an accepted ADR to rewrite history.
• Save a draft without user approval.
• list a past date as if it were known when it is not.

For an old choice, use the date the ADR is written. Add **Decision made**: YYYY-MM-DD only when the old date is known. If it is not known, write **Decision made**: Unknown.

ADR Status

proposed -> accepted -> deprecated
                     -> superseded by ADR-NNNN

• proposed: The choice is still under review.
• accepted: The choice is active.
• deprecated: The choice no longer applies.
• superseded: A newer ADR replaces it.

Do not delete an accepted ADR just because the choice changed.

To replace an ADR:

1. Create a new ADR that names the old ADR.
2. Set the new ADR status to accepted after approval.
3. Set the old ADR status to superseded by ADR-NNNN.
4. Add links in both ADR files.
5. Update both index rows.
6. Ask for approval before changing either file.

Use deprecated when a choice is no longer needed and no new ADR replaces it.

Edge Cases

• If an ADR number is missing, leave the gap.
• If two files use the same number, stop and ask which file should keep it.
• If an ADR has no options because there was only one safe choice, say why under Alternatives Considered.
• If the user asks for a draft only, return the draft in chat and do not write files.
• If the project uses another ADR folder or format, follow the project rule.
• If project rules conflict with this skill, point out the conflict and ask what to follow.
• If the work tree has user changes, do not overwrite them.
• If an ADR file or index row already exists, update it only with clear approval.
• If a choice is easy to undo and affects one small area, it may not need an ADR.
• If a choice affects safety, data loss, access, cost, or many parts of the system, it likely needs an ADR.

Concrete Example

User:

We will use PostgreSQL instead of MongoDB. We need strong links between orders, users, and payments. The team already knows SQL. MongoDB may be easier for data that changes shape, but that is not our main need. Record this choice.

Draft:

# ADR-0004: Use PostgreSQL for Core Data

**Date**: 2026-09-02
**Status**: accepted
**Deciders**: Project team

## Context

Orders, users, and payments have strong links. The team needs safe updates across this data. The team already knows SQL.

## Decision

We use PostgreSQL as the main data store for core product data.

## Alternatives Considered

### MongoDB

- **Pros**: It is easy to store data that changes shape.
- **Cons**: It gives us less help with the strong links in our core data.
- **Why not**: Flexible data shape is less important than clear links and safe updates.

## Consequences

### Positive

- The data links are clear.
- The team can use its current SQL skills.
- Safe updates can cover more than one related record.

### Negative

- Data shape changes may need more planned work.
- The team must manage table changes.

### Risks

- Poor table design could slow future changes. We will review the data model before large changes.

After showing this draft, ask the user to approve it. Only then write docs/adr/0004-use-postgresql-for-core-data.md and update the index.

Choices Worth Recording

Work With Other Skills

• When a planning skill suggests a major system change, offer to draft an ADR.
• When a review skill finds a major change with no ADR, note it and ask whether one should be added.
• Do not block work only because an ADR is missing unless the project rules require one.