dev-adr

Generate structured ADR markdown files with context, alternatives, and rationale.

1|Updated Apr 7, 2026
One-click install
npx skills add https://github.com/learnzdevelopmenthub/paadhai --skill dev-adr
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: dev-adr
Source: https://github.com/learnzdevelopmenthub/paadhai/tree/main/.claude/skills/dev-adr
Command: npx skills add https://github.com/learnzdevelopmenthub/paadhai --skill dev-adr

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Teams often overlook architecture decisions or document them inconsistently, so this skill enforces context-rich, repeatable records that surface why a change was made.

Core Features & Use Cases

  • Structured ADR Template: Generates ADR documents with sections for context, decision, alternatives, rationale, consequences, and risks, ensuring every entry follows a consistent narrative.
  • Pipeline Awareness: Detects the current git branch and related issue, reads .paadhai.json, and keeps ADR numbering in sync while providing guidance depending on whether it was invoked from dev-plan or standalone.
  • Commit Readiness: Saves the approved ADR to docs/adr with a kebab-case filename, then stages and commits the new file to keep documentation in version control.
  • Use Case: Ideal for recording high-impact architectural choices during feature planning so every stakeholder sees the rationale, alternatives considered, and next steps.

Quick Start

Ask the dev-adr skill to document the current architectural decision with the related issue context.

Frequently Asked Questions about dev-adr

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

FAQPage Schema
How do I document architecture decisions in a GitHub repository?

Documenting architecture decisions in a GitHub repository involves capturing context, alternatives, and rationale into structured markdown files. This skill automates writing records to docs/adr and commits the files directly to version control.

What sections should an architecture decision record template include?

An architecture decision record template should include sections for context, decision, alternatives, rationale, consequences, and risks. This ensures every architectural choice follows a consistent narrative for stakeholders.

How do I automate ADR numbering and commit it with the current git branch?

Automating ADR numbering requires reading .paadhai.json and detecting the current git branch. The skill keeps ADR numbering in sync, saves files with kebab-case names, and stages commits automatically.

Do I need a configuration file to generate ADRs for feature branches?

Generating ADRs for feature branches requires reading the .paadhai.json configuration file. This file provides pipeline context and related issue details to guide the architecture documentation process accurately.

What is the best way to track architecture rationale and consequences in version control?

Tracking architecture rationale in version control is best achieved by saving structured markdown files into a docs/adr directory. This approach stages and commits decisions alongside code changes to keep history aligned.

Can I record standalone architecture changes outside of a planning workflow?

Recording standalone architecture changes is fully supported alongside feature planning contexts. The skill provides specific guidance depending on whether it was invoked from a dev-plan pipeline or used independently.