existential-birds/beagle / plugins/beagle-analysis/skills/adr-writing
adr-writing
VerifiedUse when writing or formatting an ADR document using the MADR template, applying Definition of Done (E.C.A.D.R.) criteria, or verifying ADR completeness. Triggers on "write the ADR", "format as MADR", "check ADR quality", "mark gaps in ADR". Also triggers when a decision has been extracted and needs to become a document. Does NOT extract decisions from conversations (use adr-decision-extraction) or orchestrate the full extract-confirm-write workflow (use write-adr).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.2 KB |
| references/definition-of-done.md | markdown | 3.5 KB |
| references/madr-template.md | markdown | 4.2 KB |
| scripts/next_adr_number.pyexecutable | script | 3.1 KB |
references/definition-of-done.md
View on GitHub# Definition of Done: E.C.A.D.R. Criteria
An ADR is complete when it meets all five E.C.A.D.R. criteria.
## E.C.A.D.R. Checklist
### E - Explicit Problem Statement
| Check | Criteria |
|-------|----------|
| [ ] | Context describes a real, specific problem |
| [ ] | Problem is scoped (not too broad, not too narrow) |
| [ ] | Constraints and requirements are stated |
| [ ] | Reader understands WHY a decision is needed |
**Anti-patterns:**
- "We need to choose a database" (too vague)
- Problem buried in decision outcome section
- Missing business or technical context
### C - Comprehensive Options Analysis
| Check | Criteria |
|-------|----------|
| [ ] | At least 2 options considered |
| [ ] | Options are genuinely viable (not strawmen) |
| [ ] | Each option has pros AND cons listed |
| [ ] | "Do nothing" considered if applicable |
**Anti-patterns:**
- Single option presented as foregone conclusion
- Options listed without analysis
- Missing obvious alternatives
### A - Actionable Decision
| Check | Criteria |
|-------|----------|
| [ ] | Chosen option is clearly stated |
| [ ] | Decision is specific enough to implement |
| [ ] | Rationale links to decision drivers |
| [ ] | No ambiguity about what was decided |
**Anti-patterns:**
- "We will use a modern approach" (vague)
- Decision contradicts stated constraints
- Missing implementation guidance
### D - Documented Consequences
| Check | Criteria |
|-------|----------|
| [ ] | Good consequences listed |
| [ ] | Bad consequences listed (honest tradeoffs) |
| [ ] | Operational impacts considered |
| [ ] | Future implications noted |
**Anti-patterns:**
- Only positive consequences (overselling)
- Generic consequences that apply to any option
- Missing security, performance, or cost impacts
### R - Reviewable by Stakeholders
| Check | Criteria |
|-------|----------|
| [ ] | Status is set appropriately |
| [ ] | Decision-makers are identified |
| [ ] | Language is accessible (not jargon-heavy) |
| [ ] | Sufficient context for outsiders to understand |
**Anti-patterns:**
- Missing metadata (date, status, authors)
- Assumes reader context not in document
- Dense technical prose without summaries
## Quality Rubric
| Score | Criteria Met | Status |
|-------|--------------|--------|
| 5/5 | All E.C.A.D.R. criteria | Ready for `proposed` |
| 4/5 | One minor gap | Add `[INVESTIGATE]` prompt |
| 3/5 | Two gaps | Needs revision before proposing |
| 2/5 | Major gaps | Incomplete draft |
| 1/5 | Minimal content | Placeholder only |
## Using [INVESTIGATE] Prompts
When a criterion cannot be met from available information, insert an investigation prompt:
```markdown
## Decision Drivers
* Performance under 100ms response time
* [INVESTIGATE: Confirm budget constraints with finance team]
* Compatibility with existing Python stack
```
These prompts:
1. Signal incomplete sections
2. Document what information is missing
3. Enable async follow-up
4. Prevent premature status advancement
## Status Progression
```
draft ──▶ proposed ──▶ accepted
│ │
│ ▼
│ rejected
│
└──▶ [fix gaps, remove INVESTIGATE prompts]
```
Do not advance to `proposed` until all `[INVESTIGATE]` prompts are resolved.
## Review Checklist
Final pass before marking `proposed`:
- [ ] No `[INVESTIGATE]` prompts remain
- [ ] All E.C.A.D.R. criteria checked
- [ ] File named correctly (`NNNN-slugified-title.md`)
- [ ] Frontmatter complete (status, date, decision-makers)
- [ ] Links to related ADRs if superseding/related
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |