skills.rest
heimanba
heimanbaCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

documentation-and-adrs

Record architectural decisions with status, context, and consequences in ADR templates.

2|Updated Apr 9, 2026
Search Tags:#architecture#documentation#adr#rationale#software-design#decision-record#engineering-workflow
One-click install
npx skills add https://github.com/heimanba/port-lens --skill documentation-and-adrs-heimanba
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: documentation-and-adrs
Source: https://github.com/heimanba/port-lens/tree/main/.cursor/skills/documentation-and-adrs
Command: npx skills add https://github.com/heimanba/port-lens --skill documentation-and-adrs-heimanba

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

ADRs capture the rationale behind significant architectural decisions, preserving context for future engineers and avoiding rework from repeated debates.

Core Features & Use Cases

  • ADR templates and lifecycle: store decisions with status, date, context, decision, and consequences in docs/decisions/.
  • Context preservation: records constraints, trade-offs, alternatives considered, and rationale to guide future changes.
  • Onboarding & governance: aids new team members and ensures consistent decision documentation across projects.

Quick Start

Create an ADR documenting a chosen architectural decision, including problem, options, decision, and consequences.

Frequently Asked Questions about documentation-and-adrs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I document architectural decisions to preserve context for future engineers?▼

Document architectural decisions by creating Architecture Decision Records that capture status, date, context, decision, and consequences. This preserves rationale and trade-offs, preventing future teams from re-debating settled design choices.

What is an ADR and when should I use one in software design?▼

An ADR is a formal record documenting a significant architectural choice, its context, and its consequences. Use ADRs when evaluating major design choices, API changes, or infrastructure decisions to ensure governance and alignment.

How do I manage the lifecycle of an architecture decision record?▼

Manage ADR lifecycles by tracking status changes from Proposed to Accepted to Deprecated. Store sequentially numbered records in docs/decisions/ to maintain a clear history of architectural evolution and outdated decisions.

Does documenting rationale in ADRs help with onboarding new team members?▼

Yes, ADRs aid onboarding by providing historical context for new team members. Records of constraints, alternatives considered, and rationale help engineers understand past infrastructure and API decisions quickly without tribal knowledge.

What's the best way to structure decision records for software engineering workflows?▼

Structure decision records using a formal ADR template in a docs/decisions/ directory. Include problem statements, options considered, the final decision, and consequences to ensure consistent engineering workflow documentation across projects.

When should I not use an architecture decision record?▼

Avoid creating ADRs for minor implementation details or reversible choices. ADRs are designed for significant architectural decisions, API changes, and infrastructure choices where documenting trade-offs and consequences provides lasting value.

Related Skills

Explore More Software Engineering Skills→
C0ntr0lledCha0sC0ntr0lledCha0s
3

managing-docs

Automate project documentation structure and governance with configurable tooling.

Community
Advanced
oakossoakoss
2

write-spec

Formalize accepted ADRs into implementation specifications with interface boundaries and data structures.

Official
Advanced
erikliebeneriklieben
7

doc-design

Generate technical design documentation with C4 diagrams and standardized templates.

Community
Intermediate
richardnpaulrichardnpaul

architecture-decision-records

Capture and organize architectural decisions as ADR documents with context and rationale.

Community
Intermediate