adr-writer

What This Skill Does

The ADR Writer skill is a specialized developer tool designed to automate the creation of Architecture Decision Records (ADRs). Writing documentation often suffers from friction due to rigid formatting requirements and the mental overhead of drafting structured technical summaries. This skill eliminates that barrier by taking a concise, plain-English description of a technical choice and transforming it into a formal, industry-standard ADR document. It covers essential sections including the title, context, the specific decision made, and the resulting consequences, ensuring that your architectural history remains consistent, accessible, and professional.

Installation

To install this skill into your OpenClaw agent, execute the following command in your terminal:

clawhub install openclaw/skills/skills/lxgicstudios/adr-writer

Ensure that you have an active OPENAI_API_KEY environment variable configured, as the skill utilizes GPT-4o-mini to generate the intelligent, structured content required for high-quality documentation.

Use Cases

• Project Inception: Documenting foundational choices like database engines or frontend frameworks to establish a clear architectural baseline.
• Refactoring & Migration: Capturing the rationale behind moving from legacy systems to modern stacks, such as switching from REST to GraphQL or monolithic architectures to microservices.
• Team Onboarding: Providing new engineers with a historical record of why specific technical hurdles were solved in particular ways, reducing the time spent explaining past decisions.
• Compliance & Audit: Maintaining a paper trail of technical decisions required for enterprise security and quality assurance standards.

Example Prompts

1. "Generate an ADR for adopting Tailwind CSS over CSS modules to improve developer velocity and design consistency."
2. "Create an ADR documenting our decision to move from a self-hosted Jenkins setup to GitHub Actions for our CI/CD pipeline."
3. "Write an ADR for using Redis as a caching layer for our authentication service to reduce latency on high-traffic endpoints."

Tips & Limitations

• Be Specific: The AI generates higher-quality output when you provide context. Instead of 'change API', use 'switch to GraphQL to reduce over-fetching on mobile devices'.
• Review Mandatory: While the tool is excellent for boilerplate and structure, always review the generated output to ensure the consequences match your specific business constraints.
• Persistence: Treat ADRs as code. Version them in your repository alongside the code they document so that context never drifts from the implementation.