architecture-decision-records

Overview of architecture-decision-records skill

What architecture-decision-records actually helps you do

The architecture-decision-records skill helps an AI agent draft, revise, and maintain Architecture Decision Records (ADRs) with a clearer structure than a generic “write an ADR” prompt. It is built for teams that need durable technical decision documentation: why a decision was needed, what was chosen, what options were considered, and what consequences follow.

Best fit for technical writing and engineering teams

This skill is especially useful for Technical Writing, staff engineers, architects, platform teams, and engineering managers who need consistent decision records across projects. It fits best when the job is not just “write a document,” but “capture rationale in a way future readers can trust.”

The real job-to-be-done

Most teams do not struggle to invent an ADR title. They struggle to turn scattered context into a decision record that is reviewable, comparable, and useful six months later. The architecture-decision-records skill is valuable because it centers the core ADR elements—context, decision, alternatives, and consequences—rather than producing a vague architecture memo.

What differentiates this skill from a normal prompt

The main differentiator is structure. The skill is explicitly oriented around ADR best practices, including:

• when an ADR is worth writing versus overkill
• common lifecycle states such as proposed, accepted, rejected, deprecated, and superseded
• standard templates like MADR-style records
• decision-oriented framing instead of freeform prose

That makes it a better fit than ordinary prompting when you need repeatable documentation quality across many decisions.

When architecture-decision-records is a strong choice

Use the architecture-decision-records skill for decisions such as:

• adopting a new framework or platform
• choosing a database or messaging system
• defining API or integration patterns
• setting security architecture direction
• documenting tradeoffs with long-term impact

If the change is routine maintenance, a bug fix, or a minor implementation detail, this skill is usually more process than you need.

How to Use architecture-decision-records skill

Install context for architecture-decision-records

This skill lives in the wshobson/agents repository under:

plugins/documentation-generation/skills/architecture-decision-records

A common install pattern is:

npx skills add https://github.com/wshobson/agents --skill architecture-decision-records

If your environment uses a different skill loader, the key point is the slug: architecture-decision-records.

Read this file first

Start with:

SKILL.md

This repository path only exposes one meaningful source file, so there is little hidden implementation to inspect. That is good for fast adoption, but it also means your result quality depends heavily on the prompt context you provide.

What input the skill needs to work well

The architecture-decision-records skill performs best when you supply decision-ready input, not just a topic. Give the agent:

• the decision to be made
• the business or technical context
• constraints and non-goals
• alternatives already considered
• selection criteria
• known consequences or risks
• current status: proposed, accepted, rejected, deprecated, or superseded

Without this, the agent can still produce a neat ADR shell, but the rationale will be generic.

Turn a rough goal into a strong prompt

Weak prompt:

Write an ADR about using PostgreSQL.

Stronger prompt:

Draft an ADR for selecting PostgreSQL as the primary relational database for our B2B SaaS platform. Context: we are replacing a single-tenant MySQL deployment, need strong transactional guarantees, support for JSON columns, and managed cloud hosting. Alternatives considered: MySQL 8, PostgreSQL, CockroachDB. Constraints: team already knows SQL but not distributed SQL operations; must run in AWS; migration must complete within 2 quarters. Include status as Proposed, decision drivers, tradeoffs, consequences, and when this ADR should be revisited.

The second prompt gives the skill enough information to produce a decision record instead of a template with guesses.

Recommended workflow for architecture-decision-records usage

A practical architecture-decision-records usage flow is:

1. Gather the decision facts from issue threads, RFCs, or design docs.
2. Decide whether the change is ADR-worthy.
3. Ask the skill to draft the ADR in a chosen format.
4. Review for missing alternatives, weak rationale, and vague consequences.
5. Update status after review or approval.
6. Link superseding ADRs when the decision changes.

This is where the skill helps most: compressing raw decision material into a stable documentation form.

Choose a template before drafting

The source highlights a standard ADR approach and a MADR-style template. Before prompting, decide whether you want:

• a concise standard ADR
• a MADR-like structure with explicit alternatives and consequences
• a house style adapted to your repo

If your team already numbers ADRs or uses a fixed heading order, tell the skill upfront. Otherwise the agent may produce a valid ADR that still needs manual reshaping.

What to include for Technical Writing use cases

For architecture-decision-records for Technical Writing, ask the agent to optimize for future readers, not just approvers. Useful additions:

• define acronyms once
• separate context from decision drivers
• explain why rejected options were rejected
• name operational consequences, not just technical benefits
• include review triggers such as scale, compliance, or cost thresholds

That makes the document more useful for onboarding, audits, and handoffs.

Practical prompt pattern you can reuse

Use a prompt frame like this:

• Decision title
• Status
• Date or ADR number
• Context
• Problem statement
• Constraints
• Alternatives considered
• Decision
• Consequences
• Open questions
• Intended audience
• Required format or headings

This pattern reliably improves architecture-decision-records usage because it reduces invention and increases traceability.

Boundaries to understand before installing

This skill is documentation-focused. It does not validate whether your architecture choice is objectively correct. It helps you articulate rationale and tradeoffs. If your team wants benchmarking, architecture modeling, or automated policy checks, this skill should sit after those activities, not replace them.

Common repo-reading conclusion

Because the skill package is essentially just SKILL.md, adoption is straightforward: there are no helper scripts, reference bundles, or rule files to learn first. The tradeoff is that output quality comes more from your inputs and review discipline than from embedded automation.

architecture-decision-records skill FAQ

Is architecture-decision-records worth installing if I can already prompt an LLM?

Yes, if you regularly write ADRs. A generic prompt can produce one decent document, but the architecture-decision-records skill gives you a clearer default frame for repeated decision documentation. The value is consistency and fewer missed sections, especially around alternatives and consequences.

Is this beginner-friendly?

Yes. The skill explains basic ADR concepts such as context, decision, and consequences, plus when to write an ADR versus skip one. That makes it usable by teams new to ADR practice. Beginners still need to provide real project context; the skill cannot infer organizational constraints by itself.

When should I not use architecture-decision-records?

Skip it when the change is minor, routine, or purely implementation-level:

• patch upgrades
• bug fixes
• routine maintenance
• low-impact configuration changes

For those, an issue comment or changelog entry is often enough.

How is it different from an RFC?

An RFC is usually broader, more exploratory, and often written before convergence. An ADR is narrower and decision-centric. Use architecture-decision-records when you need the durable record of what was decided and why, especially after discussion has matured.

Can I use architecture-decision-records in an existing docs repo?

Yes. It fits well in repos with /docs/adr/, /adr/, or similar folders. If you already use numbering like ADR-0001, specify that in the prompt so the generated document matches your existing convention.

Does this skill help maintain old ADRs too?

Yes. The lifecycle model in the source is useful for updates: proposed, accepted, rejected, deprecated, and superseded. The skill is not only for net-new decisions; it is also useful for revising or replacing stale ADRs with clearer status and cross-links.

How to Improve architecture-decision-records skill

Give decision drivers, not just a preferred answer

The fastest way to improve architecture-decision-records output is to provide the forces behind the decision:

• scale requirements
• latency needs
• compliance obligations
• staffing constraints
• cost limits
• migration timelines

If you only state the preferred technology, the ADR will read like post-rationalization.

Provide real alternatives and why they were considered

Many weak ADRs mention one alternative in passing or invent strawman options. Better prompts list credible alternatives and why they were on the table. That gives the skill enough material to produce a useful tradeoff section instead of generic comparisons.

Be explicit about status and review triggers

Tell the skill whether the ADR is:

• Proposed
• Accepted
• Rejected
• Deprecated
• Superseded

Also state what would cause reevaluation. This improves maintenance value and keeps the ADR from looking final when it is still under review.

Ask for consequences in multiple dimensions

A stronger architecture-decision-records guide prompt asks for consequences across:

• engineering complexity
• operations
• security
• cost
• team learning curve
• future flexibility

This produces a more decision-useful ADR than a one-line “pros and cons” section.

Watch for common failure modes

Typical weak outputs include:

• generic context that could fit any project
• no rejected alternatives
• benefits without costs
• decision statements that are too broad to implement
• no indication of scope or affected systems

If you see these, the issue is usually insufficient input, not the template itself.

Iterate with targeted revision requests

After the first draft, improve it with narrow follow-ups such as:

• Tighten the decision statement to one implementable choice.
• Expand the rejected alternatives with concrete tradeoffs.
• Add operational consequences for deployment and monitoring.
• Rewrite the context so a new team member understands the trigger.
• Mark what assumptions would invalidate this ADR.

This is more effective than asking the model to “make it better.”

Adapt the output to your house ADR standard

If your organization uses a custom template, ask the skill to map the standard ADR elements into your headings. For example, you may require:

• ownership
• review date
• compliance impact
• rollout plan
• links to tickets or PRDs

The underlying architecture-decision-records install decision should depend on whether this structured drafting support fits your documentation process.

Improve long-term value with linking discipline

The best ADR collections are navigable. Ask the skill to include:

• related ADRs
• superseded-by references
• impacted systems
• links to design docs or incident reports

That turns a one-off document into part of a usable decision history.

Best way to evaluate the skill after first use

A good acceptance test is simple: can a new engineer read the generated ADR and answer:

• what problem existed
• what was decided
• what alternatives were considered
• why this option won
• what tradeoffs the team accepted
• when the decision should be revisited

If not, refine your prompt and rerun the architecture-decision-records skill with better source context.