write-adr

What This Skill Does

The write-adr skill is an essential productivity and documentation automation tool for OpenClaw agents. It serves as an architectural memory layer, designed to capture significant technical decisions made during complex interactive sessions. Rather than requiring developers to switch contexts or pause coding to write documentation, this skill acts as a proactive scribe. It analyzes the dialogue, identifies critical architectural pivots, and leverages subagents to draft structured Architecture Decision Records (ADRs) in the MADR format. By integrating repository context such as commit history and existing document directories, it ensures that generated records follow established project standards, include accurate numbering, and maintain consistent formatting.

Installation

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

Use Cases

• Project Onboarding: Automatically capture and document design decisions when bringing new team members up to speed.
• Technical Audits: Maintain a clear, immutable record of trade-offs and architectural rationale for compliance or long-term maintenance.
• Sprint Retrospectives: Use the extracted decisions as a baseline for reviewing architectural progress at the end of a development cycle.
• Refactoring Documentation: Ensure that when migrating from legacy systems to new paradigms, the 'why' and 'how' of the move is preserved permanently.

Example Prompts

1. "We just wrapped up our design session for the auth service; please trigger write-adr to document the choices we made regarding JWT implementation and OAuth integration."
2. "Review the current conversation and generate ADRs for all architectural trade-offs discussed in the last hour."
3. "Check for any pending architectural decisions in this session and write them to the docs/adrs directory using the MADR format."

Tips & Limitations

• Context is King: The skill performs best when you explicitly state, "Let's make a decision on this," during your workflow.
• Human-in-the-loop: Always verify the generated ADR before committing; while the AI is highly accurate, it may lack the broader project nuance that only a lead architect can confirm.
• Formatting: Ensure your project already has a docs/adrs directory, as the skill expects this structure to maintain sequence counts and organizational standard.