skills.rest
pirras-torres
pirras-torresCOMMUNITY
Explore all skills by this author →
GitHub

decision-docs

Creates Architecture Decision Records capturing context, options, and rationale in Markdown.

Updated May 24, 2026
Search Tags:#decision making#documentation#markdown#adr#technical design#architecture decision record
One-click install
npx skills add https://github.com/pirras-torres/pirras-marketplace --skill decision-docs-pirras-torres
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: decision-docs
Source: https://github.com/pirras-torres/pirras-marketplace/tree/main/plugins/pi-dev/skills/decision-docs
Command: npx skills add https://github.com/pirras-torres/pirras-marketplace --skill decision-docs-pirras-torres

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams often lose track of why architectural or product decisions were made, leading to repeated debates and re-litigating settled questions. This Skill interviews you and produces a structured Architecture Decision Record (ADR) so every decision is documented once and referenced forever. ## Core Features & Use Cases - Guided ADR Interview: Walks through seven focused questions covering context, options with pros and cons, the decision, rationale, consequences, and reversibility. - Automatic Numbering and Naming: Detects existing ADRs in docs/06_decisions/ and generates the next sequentially numbered file like adr-3-database-choice.md. - Multi-Decision Support: Runs the full interview sequentially for each decision when several need documenting. - Use Case: After choosing PostgreSQL over MongoDB for your backend, use this Skill to record the context, the alternatives considered, and the trigger conditions that would reopen the decision. ## Quick Start Ask the assistant to document an architectural decision as an ADR using the decision-docs skill.

Frequently Asked Questions about decision-docs

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

FAQPage Schema
How do I create an Architecture Decision Record?▼

Run the decision-docs skill and answer seven guided questions about the decision's context, options considered, final choice, rationale, and consequences. The skill writes a formatted ADR Markdown file to docs/06_decisions/ automatically.

What should an ADR document contain?▼

An ADR should contain the decision question as title, status and date, context explaining why the decision was needed, options with pros and cons, the decision and rationale, consequences, and a revisit trigger describing what would reopen it.

How are ADR files numbered and named?▼

The skill counts existing adr-*.md files in docs/06_decisions/ and increments the number for the new file. Names follow the pattern adr-[number]-[short-slug].md, such as adr-3-database-choice.md.

Can I document multiple decisions at once?▼

Yes, the skill runs the full interview sequentially for each decision. Every decision gets its own separate ADR file, since the format requires one decision per record.

What happens if no docs folder exists in my project?▼

The skill searches for a docs directory up to three levels deep, excluding node_modules and .git. If none is found, it defaults to docs/ and creates the folder including 06_decisions/ if missing.

Related Skills

Explore More Software Engineering Skills→
phant-appphant-app

interview

Conduct structured technical interviews to refine implementation plans.

Official
Intermediate
huangzidahuangzida
2

documentation-and-adrs

Document architectural decisions and ADRs under docs/decisions with sequential numbering.

Community
Intermediate
anthropicsanthropics
23.4k

risk-assessment

Identify, assess, and plan mitigations for operational risks in a structured register.

Official
Intermediate
videojsvideojs
888

rfc

Formalize Video.js 10 direction proposals with structured RFC documents.

Official
Basic