Add writing-adrs skill for ADR authoring guidance

[ralphbean]

Adds a skill in skills/writing-adrs/ that guides agents through writing Architecture Decision Records. Key behaviors enforced:

• One decision per ADR (split if multiple decisions emerge)
• Concise writing with length targets per section
• Link to problem docs instead of restating their content
• Follow the repo's ADR template and frontmatter schema
• Run make lint before committing
• Update docs/architecture.md and problem docs when an ADR is accepted
• Use strikethrough annotations on resolved open questions

Developed using TDD: baseline test showed agents writing verbose, multi-decision ADRs that restated problem doc content. The skill corrects these patterns.

Assisted-by: OpenCode claude-opus-4-6@default

[qodo-code-review]

Review Summary by Qodo

Add writing-adrs skill for ADR authoring guidance

✨ Enhancement 📝 Documentation

Walkthroughs

Description

• Adds comprehensive skill guide for writing Architecture Decision Records
• Enforces one-decision-per-ADR pattern with conciseness targets
• Provides checklist, templates, and linting requirements
• Includes rules for updating living docs after ADR acceptance

Diagram

flowchart LR
  A["Problem Docs<br/>Exploration"] -->|"Decision<br/>Crystallizes"| B["ADR Skill<br/>Guidance"]
  B -->|"One Decision<br/>Per ADR"| C["ADR Template<br/>& Checklist"]
  C -->|"Accepted ADRs"| D["Update Living<br/>Documents"]
  D -->|"architecture.md<br/>& Problem Docs"| E["Current State<br/>Reflects Decision"]

Loading

File Changes

1. skills/writing-adrs/SKILL.md 📝 Documentation +155/-0

Comprehensive ADR authoring skill with enforcement rules

• Introduces comprehensive ADR authoring skill with overview and usage guidelines
• Defines core rules: one decision per ADR, conciseness targets (under 80 lines), linking to problem
 docs instead of restating
• Provides step-by-step checklist covering numbering, template usage, frontmatter, status selection,
 linting, and document updates
• Includes detailed guidance for updating docs/architecture.md and problem docs after ADR
 acceptance with strikethrough annotations for resolved questions
• Lists red flags and common mistakes with fixes to prevent anti-patterns

skills/writing-adrs/SKILL.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 📐 Spec deviations (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

ⓘ The new review experience is currently in Beta. Learn more