After adoping the obra/superpowers workflow, design docs became an important part of my coding process. They’re detailed and verbose - containing code snippets, specific tasks and implementation procedures, and tests - perfect for handing off to subagents for implementation. But after the feature is built, I couldn’t decide whether to include them as part of my git history or to discard them. 95% of their content will probably never be consumed by either me or LLMs ever again, but they do contain little snippets of historical context that may be important for future architectural decisions.
So, let’s create a Skill to create architectural decision records (ADRs) from these design documents. ADRs become important as the repo, codebase, and team grows. An anecdote:
We instituted ADRs as a way of recording an architecture decision, with pros and cons, with comparisons to other alternatives and with the names, titles, and commitments of various executives so that a decision would not be relitigated every time someone new complained that “there’s an easier way … Any time someone (especially someone new) complained about using a cloud based messaging platform, we would point them to the document and they had a one on one with the chief architect afterwards. They had to present a new argument, not already covered in the ADR, before anyone else would get involved. - (reddit - What are ADRs)
It is common for ADRs to get created before design docs. My use case may be unique – I want to turn design docs into ADRs. Perhaps this explains why not many Skills for creating ADRs exist as of March 2026. However, this blog post by Dennis Adolfi provides an excellent starting point for this exercise.
Folder Structure
Create a folder to house the ADRs, like this:
ADR/
├── overview.md
├── template.md
└── records/
├── 001_use-this-pattern-to-query-data.md
├── 002_use-that-pattern-to-store-data.md
└── 003_use-another-pattern-to-store-data-instead.md
Overview.md
The overview.md file serves as an index, containing:
- A brief introduction to what ADRs are.
- Instructions for humans and agents to follow when creating new records.
- A table linking to all existing ADRs with their status and date.
# Architecture Decision Records (ADR)
## What is an ADR?
An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along with its context and
consequences. ADRs help teams:
- Document decisions – Keep a historical record of why certain choices were made
- Share knowledge – Help new team members understand the reasoning behind the architecture
- Enable discussion – Provide a structured format for proposing and reviewing decisions
- Track changes – See how the architecture has evolved over time
## How to Create a New ADR
1. Copy the template from template.md
2. Save it in the records/ folder with the naming pattern: NNN_title-of-the-adr.md
- Use the next available number (e.g., 001, 002, 003)
- Use lowercase with hyphens for the title (e.g., 001_use-postgresql-database.md)
3. Fill in all sections of the template
4. Add an entry to the table below
## ADR Index
┌─────┬──────────────────────────────────────────────┬──────────┬────────────┐
│ # │ Title │ Status │ Date │
├─────┼──────────────────────────────────────────────┼──────────┼────────────┤
│ 001 │ No Controllers for Model Rendering │ Accepted │ 2025-11-24 │
├─────┼──────────────────────────────────────────────┼──────────┼────────────┤
│ 002 │ Use InMemoryAuto Models Builder Mode │ Accepted │ 2025-11-24 │
├─────┼──────────────────────────────────────────────┼──────────┼────────────┤
│ 003 │ Use Block List Pattern for Content Structure │ Accepted │ 2025-11-24 │
└─────┴──────────────────────────────────────────────┴──────────┴────────────┘
Template.md
[ADR-001] No Controllers for Model Rendering
## Status
Accepted
## Date
<YYYY-MM-DD>
## Author
<github user>
## Context
When building the application architecture, a decision needed to be made about how models are rendered and presented. Traditional MVC
(Model-View-Controller) patterns use controllers as an intermediary layer between models and views.
## Decision
We will not use controllers for rendering models. Models will be rendered directly without a controller layer acting as an intermediary.
## Consequences
What becomes easier or more difficult to do because of this change?
- Simpler architecture – Fewer layers means less code to maintain and understand
- Faster development – No need to create and wire up controller classes for each model
- Direct data flow – Clear path from model to view without intermediate transformation
- Less flexibility – Complex view logic may need to be handled elsewhere
- Tighter coupling – Views may become more directly coupled to model structure
This makes it easy to browse all decisions at a glance and navigate to specific records.
ADR Skill
Use superpower’s writing-skill Skill to create the skill. The prompt:
create a skill that creates architectural decision records (ADR) from design documents. It should scan the design doc, extract relevant context, then either create a new ADR document or update an existing one. Reference this markdown file for what I have in mind.
The result. I’ll iterate on this as I use it more.
Usage
Add to your commit flow:
Invoke the adr skill. Once accepted by user, remove the design and implementation docs.
Add to the reference index section of your CLAUDE.md or AGENT.md file:
Architectural Decision Records: ./ADR/overview.md