adr-writing

What This Skill Does

The adr-writing skill provides an automated, standardized approach to generating Architectural Decision Records (ADRs) within the OpenClaw ecosystem. By adhering to the MADR (Markdown Architectural Decision Records) template, this skill ensures that all technical decisions are documented with consistency, clarity, and historical traceability. The agent follows a multi-step workflow—sequence allocation, context exploration, template population, and a rigorous Definition of Done (DoD) verification—to transform raw technical discussions into professional, reviewable documentation. It minimizes the overhead of technical debt management by prompting for missing information and ensuring that every decision is backed by explicit context, rationale, and consequences.

Installation

To integrate this skill into your OpenClaw environment, execute the following command in your terminal: clawhub install openclaw/skills/skills/anderskev/adr-writing

Use Cases

This skill is ideal for:

• Converting informal Slack or GitHub PR discussions into formal architectural records.
• Standardizing documentation across large teams using the MADR format.
• Ensuring that every major design choice is vetted against the E.C.A.D.R. criteria before being committed.
• Managing complex project evolution where legacy decisions need to be captured or superseded.

Example Prompts

1. "Analyze the recent PR #452 regarding the database migration and generate an ADR using the adr-writing skill."
2. "I need to document our decision to switch from REST to GraphQL for the new mobile API. Use the adr-writing skill and help me fill out the considered options."
3. "Review the current state of our infrastructure decisions; identify any gaps in the existing documentation and draft a new ADR for the load balancing strategy."

Tips & Limitations

• Pre-allocation: If you are running multiple ADR generation tasks simultaneously, remember to use the --count flag with the sequence script to avoid index collisions.
• Gap Filling: Do not fear the 'gap' prompts; they are designed to highlight what you do not yet know. Marking these early prevents the 'illusion of completeness' often found in rushed documentation.
• Iterative Refinement: While the skill provides a strong draft, architectural decisions are often social as much as technical; always use the output as a starting point for stakeholder review rather than a final product.