documentation-and-adrs
Documentation and ADRs helps teams record the reasoning behind significant technical decisions through structured Architecture Decision Records. Store decisions in `docs/decisions/` with context, alternatives considered, and consequences so future engineers and AI agents understand not just what was built, but why.
Documentation and ADRs captures the reasoning behind technical decisions using structured architecture decision records.
AI-generated summary based on this skill's SKILL.md
Decision gist · record as of 2026-07-24
Documentation and ADRs captures the reasoning behind technical decisions using structured architecture decision records. Documentation and ADRs helps teams record the reasoning behind significant technical decisions through structured Architecture Decision Records. Store decisions in `docs/decisions/` with context, alternatives considered, and consequences so future engineers and AI agents understand not just what was built, but why.
Use it when
- Documentation and ADRs recommends writing ADRs whenever you make significant architectural choices—database selections, framework decisions.
- Documentation and ADRs suggests a template with sections for title, status, context (the problem driving the decision).
Verify before relying
Read SKILL.md below before installing (1 file). Open directory: indexed for reading, not audited.
Similar skills
Install
shashankswe2020-ux/whoop-mcp/documentation-and-adrs · repository language: TypeScript
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to write architecture decision records?
Documentation and ADRs guides you to structure each ADR with a clear title, context explaining the problem, decision statement, alternatives considered, and consequences. Store records in `docs/decisions/` so your team and AI agents can trace why technical choices were made. Include enough detail that someone unfamiliar with the project understands both the reasoning and trade-offs without needing to ask the original author.
When should I write ADRs for my project?
Documentation and ADRs recommends writing ADRs whenever you make significant architectural choices—database selections, framework decisions, API design patterns, or major refactors. Capture decisions early rather than retroactively; this preserves engineering context for onboarding and helps future maintainers (including AI agents) understand not just what was built, but why certain alternatives were rejected.
What is an ADR template for technical decisions?
Documentation and ADRs suggests a template with sections for title, status, context (the problem driving the decision), decision (what you chose), alternatives (options you considered and rejected), and consequences (trade-offs and impacts). This structure ensures decisions are documented consistently across your project and captures the reasoning needed for long-term maintenance and knowledge transfer.
How do I document design trade-offs and rejected alternatives?
Documentation and ADRs emphasizes recording alternatives considered and why each was rejected in your ADR's alternatives section. Explicitly state the trade-offs: what you gained by choosing your solution and what you sacrificed. This prevents future engineers from re-debating settled decisions and helps new team members understand the constraints and priorities that shaped your architecture.
What inline documentation best practices should I follow?
Documentation and ADRs recommends writing inline comments for non-obvious code behavior, gotchas, and the reasoning behind complex logic—not for self-explanatory code. Link comments to related ADRs when architectural decisions influenced implementation. This preserves context for maintainers and reduces onboarding friction, especially when AI agents need to understand intent beyond syntax.
How should I structure a project README and documentation standards?
Documentation and ADRs suggests establishing standards that include a clear README with project purpose, setup instructions, and links to decision records; API documentation; and a `docs/decisions/` folder for ADRs. Consistent structure helps new team members and AI agents navigate your project's technical landscape and understand both current architecture and the reasoning behind it.
SKILL.md
Rendered from the published skill. Quoted content, verbatim.
Documentation and ADRs
Overview
Document decisions, not just code. The most valuable documentation captures the why — the context, constraints, and trade-offs that led to a decision. Code shows what was built; documentation explains why it was built this way and what alternatives were considered. This context is essential for future humans and agents working in the codebase.
When to Use
- Making a significant architectural decision
- Choosing between competing approaches
- Adding or changing a public API
- Shipping a feature that changes user-facing behavior
- Onboarding new team members (or agents) to the project
- When you find yourself explaining the same thing repeatedly
When NOT to use: Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.
Architecture Decision Records (ADRs)
ADRs capture the
(truncated - see the full file via the links below)
File tree — 1 file
.github/skills/documentation-and-adrs/SKILL.md
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Write architecture decision records to capture why technical choices were made”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
This skill guides you to document decisions that matter—architectural choices, API shifts, and feature launches—by capturing the reasoning, constraints, and alternatives considered. It includes templates for Architecture Decision Records (ADRs) that preserve historical context, inline documentation patterns that explain intent rather than restating code, and structures for API and README documentation that help current and future engineers understand not just what was built, but why.
Capture significant technical choices in a structured format that explains the problem, alternatives weighed, and reasoning behind your decision. Use the provided template to create numbered records in your docs folder, then reference them from code comments when relevant. This ensures your team understands not just what was decided, but why—making it easier to revisit or build on those choices later.
The ADR skill helps you record major architectural choices in a structured format that captures the reasoning behind decisions, not just the outcome. It stores numbered records in your project's docs folder and guides you through context, trade-offs, and consequences so your team can understand why decisions were made.
Architecture guides decision-making through requirements analysis, trade-off evaluation, and ADR documentation. It helps teams capture design rationale and choose patterns systematically, emphasizing simplicity and constraint-aware choices.
Technical Writing guides you through creating durable internal documentation for builders and operators—specs, architecture decisions, runbooks, migration paths, and implementation guides. It helps you classify your document type, gather evidence, choose the right structure, and apply mode-specific writing rules to keep technical knowledge clear and actionable.
Add comprehensive JSDoc comments to TypeScript codebases to document functions, interfaces, types, and classes with parameters, return types, and usage examples. Includes patterns for async functions, generics, overloads, and class methods to support automated API documentation generation.
More skills documentation-patterns (MIT) · architecture-decision-records (MIT) · Create Adr (NOASSERTION) · adr-writer (MIT) · architecture-decision-record (MIT) · Adr Skill (unlicensed)