Index of every page on this site: llms.txt
All skills
wshobson avatar

/architecture-decision-records

@4220308
by Seth Hobsonwshobson/agents43k stars
4,518
Run it yourself

Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.

Use this Skill: https://skilld.dev/gh/wshobson/agents/architecture-decision-records

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesdeprecation-rfc-templates.md

≈859 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Template 4: ADR for Deprecation

# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL

## Status

Accepted (Supersedes ADR-0003)

## Context

ADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility
needs. Since then:

- MongoDB's multi-document transactions remain problematic for our use case
- Our schema has stabilized and rarely changes
- We now have PostgreSQL expertise from other services
- Maintaining two databases increases operational burden

## Decision

Deprecate MongoDB and migrate user profiles to PostgreSQL.

## Migration Plan

1. **Phase 1** (Week 1-2): Create PostgreSQL schema, dual-write enabled
2. **Phase 2** (Week 3-4): Backfill historical data, validate consistency
3. **Phase 3** (Week 5): Switch reads to PostgreSQL, monitor
4. **Phase 4** (Week 6): Remove MongoDB writes, decommission

## Consequences

### Positive

- Single database technology reduces operational complexity
- ACID transactions for user data
- Team can focus PostgreSQL expertise

### Negative

- Migration effort (~6 weeks)
- Risk of data issues during migration
- Lose some schema flexibility

## Lessons Learned

Document from ADR-0003 experience:

- Schema flexibility benefits were overestimated
- Operational cost of multiple databases was underestimated
- Consider long-term maintenance in technology decisions

Template 5: Request for Comments (RFC) Style

# RFC-0025: Adopt Event Sourcing for Order Management

## Summary

Propose adopting event sourcing pattern for the order management domain to
improve auditability, enable temporal queries, and support business analytics.

## Motivation

Current challenges:

1. Audit requirements need complete order history
2. "What was the order state at time X?" queries are impossible
3. Analytics team needs event stream for real-time dashboards
4. Order state reconstruction for customer support is manual

## Detailed Design

### Event Store

OrderCreated { orderId, customerId, items[], timestamp } OrderItemAdded { orderId, item, timestamp } OrderItemRemoved { orderId, itemId, timestamp } PaymentReceived { orderId, amount, paymentId, timestamp } OrderShipped { orderId, trackingNumber, timestamp }


### Projections

- **CurrentOrderState**: Materialized view for queries
- **OrderHistory**: Complete timeline for audit
- **DailyOrderMetrics**: Analytics aggregation

### Technology

- Event Store: KurrentDB, formerly EventStoreDB (purpose-built, handles projections)
- Alternative considered: Kafka + custom projection service

## Drawbacks

- Learning curve for team
- Increased complexity vs. CRUD
- Need to design events carefully (immutable once stored)
- Storage growth (events never deleted)

## Alternatives

1. **Audit tables**: Simpler but doesn't enable temporal queries
2. **CDC from existing DB**: Complex, doesn't change data model
3. **Hybrid**: Event source only for order state changes

## Unresolved Questions

- [ ] Event schema versioning strategy
- [ ] Retention policy for events
- [ ] Snapshot frequency for performance

## Implementation Plan

1. Prototype with single order type (2 weeks)
2. Team training on event sourcing (1 week)
3. Full implementation and migration (4 weeks)
4. Monitoring and optimization (ongoing)

## References

- [Event Sourcing by Martin Fowler](https://martinfowler.com/eaaDev/EventSourcing.html)
- [KurrentDB Documentation](https://docs.kurrent.io/)

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo5 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill provides comprehensive guidelines and templates for documenting technical decisions through Architecture Decision Records (ADRs). It references official documentation for reputable database technologies and standard developer tools. No security risks were identified.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

  • Runlayer8mo

    1/1 file flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 4220308. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated last month
  • Documentation
  • adr
  • architecture
  • decision-records
  • decision-making
  • technical-decisions
  • design-patterns
  • process

README badge

README badge for wshobson/agents/architecture-decision-records

Captures context, decision, and consequences for significant technical choices using templates like MADR format, lightweight ADR, and Y-statements. Includes patterns for managing ADR lifecycles, deprecations, and review processes with directory structure and automation tools.

Generated from the current SKILL.md.

What format should I use for writing ADRs?
The skill provides five templates: Standard ADR (MADR format with full context and rationale), Lightweight ADR (minimal format for simpler decisions), Y-Statement (concise single-paragraph format), Deprecation ADR (for superseding prior decisions), and RFC-style (for proposals requiring team discussion). Choose based on decision complexity and team needs.
When should I write an ADR versus skip it?
Write ADRs for significant decisions like framework adoption, database choice, API design, and security architecture. Skip them for minor version upgrades, bug fixes, implementation details, and routine maintenance.
How do I manage ADRs as a team?
Organize ADRs in a `docs/adr/` directory with sequential numbering, maintain an index README, use a review checklist, and optionally automate with adr-tools. The skill includes templates for directory structure, an ADR index, and a review process.
How do I handle decisions that change or become obsolete?
Mark the original ADR as Deprecated or Superseded and create a new ADR explaining the context change, why the old decision no longer fits, and the migration plan. Link the two ADRs together for traceability.
Can I use lightweight ADRs or must I follow the full template?
The skill supports multiple formats from lightweight (status, context, decision, consequences in minimal form) to comprehensive. Choose the format that matches your decision's scope and team process.

Generated from the current SKILL.md. These answers refresh after source changes.