skills.rest
josuenavarroaguado
josuenavarroaguadoCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

documentation-and-adrs

Record and organize architecture and design decisions using ADR templates.

1|Updated Jan 28, 2025
Search Tags:#changelog#documentation#onboarding#adr#readme#architecture-decisions#api-documentation
One-click install
npx skills add https://github.com/josuenavarroaguado/josuenavarroaguado.github.io --skill documentation-and-adrs-josuenavarroaguado
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: documentation-and-adrs
Source: https://github.com/josuenavarroaguado/josuenavarroaguado.github.io/tree/main/.github/skills/documentation-and-adrs
Command: npx skills add https://github.com/josuenavarroaguado/josuenavarroaguado.github.io --skill documentation-and-adrs-josuenavarroaguado

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Teams and future contributors lose critical context when rationale, trade-offs, and decision history are not recorded; this Skill ensures the why behind code and design is preserved so engineers and agents can make informed changes without redoing past analysis.

Core Features & Use Cases

  • ADR templates & lifecycle: Provides a consistent ADR format and lifecycle guidance (PROPOSED → ACCEPTED → SUPERSEDED/DEPRECATED) so decisions are discoverable and traceable.
  • Inline documentation guidance: Explains when to comment, what to record in code, and how to document gotchas that prevent repeated mistakes.
  • Project README & changelog standards: Defines README structure, changelog maintenance, and agent-facing docs to support onboarding, API changes, and release notes.

Quick Start

Create an ADR in docs/decisions using the ADR template and record Context, Decision, Alternatives, and Consequences with an initial status of PROPOSED.

Frequently Asked Questions about documentation-and-adrs

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

FAQPage Schema
How do I record architectural decisions so future contributors understand the rationale?▼

You record architectural decisions by creating an ADR in docs/decisions using a template that captures Context, Decision, Alternatives, and Consequences with an initial status of PROPOSED. This preserves the why behind design choices so engineers don't redo past analysis.

What is the ADR lifecycle for tracking architecture decisions in a repository?▼

The ADR lifecycle follows a status progression from PROPOSED to ACCEPTED, then to SUPERSEDED or DEPRECATED. This lifecycle tracking ensures that architecture decisions remain discoverable and traceable as the project evolves.

How should I structure project README and changelog documentation for onboarding?▼

Structure your README and changelog using defined standards that support onboarding, API changes, and release notes. This includes agent-facing docs that help new engineers and automated agents understand the project context and navigate architectural changes.

When do I need to write inline documentation versus creating a full architecture decision record?▼

Write inline documentation to explain when to comment, what to record in code, and how to document gotchas that prevent repeated mistakes. Create a full ADR when you need to record broader architectural trade-offs, alternatives, and consequences for future reference.

Does this approach to recording architecture decisions work for tracking API changes?▼

Yes, recording architecture decisions supports tracking API changes by maintaining changelog standards and agent-facing documentation. This ensures that API evolution and architectural changes are documented for onboarding and release notes.

What are the limitations of relying only on inline code comments instead of architecture decision records?▼

Inline comments explain localized gotchas but lose critical context regarding broader trade-offs and decision history. Without ADRs, teams lack a discoverable record of alternatives and consequences, forcing future contributors to redo past analysis.

Related Skills

Explore More Software Engineering Skills→
tradertunantetradertunante

documentation-and-adrs

Record architectural decisions and documentation within the repository.

Community
Advanced
frostantfrostant
42

changelog-generator

Converts git commit history into categorized, ready-to-publish markdown release notes.

Community
Intermediate
Mte90Mte90
51

Documentation Standards

Enforce documentation standards for code comments, READMEs, and architectural docs.

Community
Basic
LetPeopleWorkLetPeopleWork
16

architecture-patterns

Document architecture decisions and patterns using ADR templates.

Official
Basic