From adr
This skill should be used when the user asks about "ADR quality", "review ADR", "ADR checklist", "improve ADR", "ADR validation", "good ADR examples", or needs guidance on evaluating, improving, and maintaining high-quality architectural decision records.
npx claudepluginhub zircote/adrThis skill uses the workspace's default tool permissions.
This skill provides guidance on creating, evaluating, and maintaining high-quality Architectural Decision Records. Quality ADRs are clear, complete, and useful for future readers.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
This skill provides guidance on creating, evaluating, and maintaining high-quality Architectural Decision Records. Quality ADRs are clear, complete, and useful for future readers.
| Criterion | Definition | Questions to Ask |
|---|---|---|
| Clear | Easy to understand | Can a new team member understand this? |
| Complete | All relevant information | Are all sections filled out meaningfully? |
| Concise | No unnecessary content | Is every sentence adding value? |
| Contextual | Sufficient background | Is the "why" clear? |
| Current | Reflects actual state | Is the status accurate? Are links valid? |
Good titles are:
| Quality | Example |
|---|---|
| Good | "Use PostgreSQL for primary data storage" |
| Good | "Adopt event-driven architecture for order processing" |
| Bad | "Database" |
| Bad | "Technical decision about which database to use for storing user data" |
Context should answer:
Good context example:
Our e-commerce platform needs to handle user authentication across
mobile and web applications. Currently, authentication is handled
separately in each app, leading to inconsistent security and duplicate
code. We have 50,000 active users and expect 10x growth in 2 years.
The team has experience with OAuth but not SAML.
Drivers should be:
Each option should have:
The decision should:
Consequences should include:
| Anti-Pattern | Description | Fix |
|---|---|---|
| Thin Context | Just problem statement, no background | Add current state, constraints, stakeholders |
| Missing Trade-offs | Only benefits listed | Document negatives of chosen option |
| Straw Man Options | Options included just to reject | Only include seriously considered alternatives |
| Vague Drivers | Generic terms like "performance" | Add specific, measurable criteria |
| Orphan ADRs | No links to related decisions | Add supersedes/relates-to links |
| Stale Status | Status doesn't reflect reality | Update status when state changes |
| Hindsight Bias | Written long after decision | Create ADRs during decision process |
Before submitting an ADR:
Completeness
Clarity
Accuracy
When reviewing ADRs:
Ask these during review:
Good: "We chose PostgreSQL for its strong JSON support" Bad: "The database was selected based on various factors"
| Section | Recommended Length |
|---|---|
| Title | 5-15 words |
| Context | 100-300 words |
| Decision Drivers | 3-8 items |
| Options | 2-5 options, 50-150 words each |
| Decision | 50-150 words |
| Consequences | 100-300 words |
Periodically review ADRs for:
Keep status current:
Ensure ADRs connect to:
| Metric | Good | Concerning | Critical |
|---|---|---|---|
| Sections completed | >90% | 70-90% | <70% |
| Options considered | 2-5 | 1 or >5 | 0 |
| Consequences documented | Both +/- | Only + | None |
| Status currency | Updated monthly | Quarterly | >6 months |
| Links working | 100% | >90% | <90% |