@zimezone/z-command 1.1.1 → 1.1.2

package/templates/skills/architecture-decision-records/SKILL.md

@@ -1,428 +0,0 @@
----
-name: architecture-decision-records
-description: 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.
----
-
-# Architecture Decision Records
-
-Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.
-
-## When to Use This Skill
-
-- Making significant architectural decisions
-- Documenting technology choices
-- Recording design trade-offs
-- Onboarding new team members
-- Reviewing historical decisions
-- Establishing decision-making processes
-
-## Core Concepts
-
-### 1. What is an ADR?
-
-An Architecture Decision Record captures:
-- **Context**: Why we needed to make a decision
-- **Decision**: What we decided
-- **Consequences**: What happens as a result
-
-### 2. When to Write an ADR
-
-| Write ADR | Skip ADR |
-|-----------|----------|
-| New framework adoption | Minor version upgrades |
-| Database technology choice | Bug fixes |
-| API design patterns | Implementation details |
-| Security architecture | Routine maintenance |
-| Integration patterns | Configuration changes |
-
-### 3. ADR Lifecycle
-
-```
-Proposed → Accepted → Deprecated → Superseded
-              ↓
-           Rejected
-```
-
-## Templates
-
-### Template 1: Standard ADR (MADR Format)
-
-```markdown
-# ADR-0001: Use PostgreSQL as Primary Database
-
-## Status
-
-Accepted
-
-## Context
-
-We need to select a primary database for our new e-commerce platform. The system
-will handle:
-- ~10,000 concurrent users
-- Complex product catalog with hierarchical categories
-- Transaction processing for orders and payments
-- Full-text search for products
-- Geospatial queries for store locator
-
-The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID
-compliance for financial transactions.
-
-## Decision Drivers
-
-* **Must have ACID compliance** for payment processing
-* **Must support complex queries** for reporting
-* **Should support full-text search** to reduce infrastructure complexity
-* **Should have good JSON support** for flexible product attributes
-* **Team familiarity** reduces onboarding time
-
-## Considered Options
-
-### Option 1: PostgreSQL
-- **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text
-  search, PostGIS for geospatial, team has experience
-- **Cons**: Slightly more complex replication setup than MySQL
-
-### Option 2: MySQL
-- **Pros**: Very familiar to team, simple replication, large community
-- **Cons**: Weaker JSON support, no built-in full-text search (need
-  Elasticsearch), no geospatial without extensions
-
-### Option 3: MongoDB
-- **Pros**: Flexible schema, native JSON, horizontal scaling
-- **Cons**: No ACID for multi-document transactions (at decision time),
-  team has limited experience, requires schema design discipline
-
-## Decision
-
-We will use **PostgreSQL 15** as our primary database.
-
-## Rationale
-
-PostgreSQL provides the best balance of:
-1. **ACID compliance** essential for e-commerce transactions
-2. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce
-   infrastructure complexity
-3. **Team familiarity** with SQL databases reduces learning curve
-4. **Mature ecosystem** with excellent tooling and community support
-
-The slight complexity in replication is outweighed by the reduction in
-additional services (no separate Elasticsearch needed).
-
-## Consequences
-
-### Positive
-- Single database handles transactions, search, and geospatial queries
-- Reduced operational complexity (fewer services to manage)
-- Strong consistency guarantees for financial data
-- Team can leverage existing SQL expertise
-
-### Negative
-- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)
-- Vertical scaling limits may require read replicas sooner
-- Some team members need PostgreSQL-specific training
-
-### Risks
-- Full-text search may not scale as well as dedicated search engines
-- Mitigation: Design for potential Elasticsearch addition if needed
-
-## Implementation Notes
-
-- Use JSONB for flexible product attributes
-- Implement connection pooling with PgBouncer
-- Set up streaming replication for read replicas
-- Use pg_trgm extension for fuzzy search
-
-## Related Decisions
-
-- ADR-0002: Caching Strategy (Redis) - complements database choice
-- ADR-0005: Search Architecture - may supersede if Elasticsearch needed
-
-## References
-
-- [PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.html)
-- [PostgreSQL Full Text Search](https://www.postgresql.org/docs/current/textsearch.html)
-- Internal: Performance benchmarks in `/docs/benchmarks/database-comparison.md`
-```
-
-### Template 2: Lightweight ADR
-
-```markdown
-# ADR-0012: Adopt TypeScript for Frontend Development
-
-**Status**: Accepted
-**Date**: 2024-01-15
-**Deciders**: @alice, @bob, @charlie
-
-## Context
-
-Our React codebase has grown to 50+ components with increasing bug reports
-related to prop type mismatches and undefined errors. PropTypes provide
-runtime-only checking.
-
-## Decision
-
-Adopt TypeScript for all new frontend code. Migrate existing code incrementally.
-
-## Consequences
-
-**Good**: Catch type errors at compile time, better IDE support, self-documenting
-code.
-
-**Bad**: Learning curve for team, initial slowdown, build complexity increase.
-
-**Mitigations**: TypeScript training sessions, allow gradual adoption with
-`allowJs: true`.
-```
-
-### Template 3: Y-Statement Format
-
-```markdown
-# ADR-0015: API Gateway Selection
-
-In the context of **building a microservices architecture**,
-facing **the need for centralized API management, authentication, and rate limiting**,
-we decided for **Kong Gateway**
-and against **AWS API Gateway and custom Nginx solution**,
-to achieve **vendor independence, plugin extensibility, and team familiarity with Lua**,
-accepting that **we need to manage Kong infrastructure ourselves**.
-```
-
-### Template 4: ADR for Deprecation
-
-```markdown
-# 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 (~4 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
-
-```markdown
-# 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: 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)
-- [EventStoreDB Documentation](https://www.eventstore.com/docs)
-```
-
-## ADR Management
-
-### Directory Structure
-
-```
-docs/
-├── adr/
-│   ├── README.md           # Index and guidelines
-│   ├── template.md         # Team's ADR template
-│   ├── 0001-use-postgresql.md
-│   ├── 0002-caching-strategy.md
-│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]
-│   └── 0020-deprecate-mongodb.md      # Supersedes 0003
-```
-
-### ADR Index (README.md)
-
-```markdown
-# Architecture Decision Records
-
-This directory contains Architecture Decision Records (ADRs) for [Project Name].
-
-## Index
-
-| ADR | Title | Status | Date |
-|-----|-------|--------|------|
-| [0001](0001-use-postgresql.md) | Use PostgreSQL as Primary Database | Accepted | 2024-01-10 |
-| [0002](0002-caching-strategy.md) | Caching Strategy with Redis | Accepted | 2024-01-12 |
-| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles | Deprecated | 2023-06-15 |
-| [0020](0020-deprecate-mongodb.md) | Deprecate MongoDB | Accepted | 2024-01-15 |
-
-## Creating a New ADR
-
-1. Copy `template.md` to `NNNN-title-with-dashes.md`
-2. Fill in the template
-3. Submit PR for review
-4. Update this index after approval
-
-## ADR Status
-
-- **Proposed**: Under discussion
-- **Accepted**: Decision made, implementing
-- **Deprecated**: No longer relevant
-- **Superseded**: Replaced by another ADR
-- **Rejected**: Considered but not adopted
-```
-
-### Automation (adr-tools)
-
-```bash
-# Install adr-tools
-brew install adr-tools
-
-# Initialize ADR directory
-adr init docs/adr
-
-# Create new ADR
-adr new "Use PostgreSQL as Primary Database"
-
-# Supersede an ADR
-adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"
-
-# Generate table of contents
-adr generate toc > docs/adr/README.md
-
-# Link related ADRs
-adr link 2 "Complements" 1 "Is complemented by"
-```
-
-## Review Process
-
-```markdown
-## ADR Review Checklist
-
-### Before Submission
-- [ ] Context clearly explains the problem
-- [ ] All viable options considered
-- [ ] Pros/cons balanced and honest
-- [ ] Consequences (positive and negative) documented
-- [ ] Related ADRs linked
-
-### During Review
-- [ ] At least 2 senior engineers reviewed
-- [ ] Affected teams consulted
-- [ ] Security implications considered
-- [ ] Cost implications documented
-- [ ] Reversibility assessed
-
-### After Acceptance
-- [ ] ADR index updated
-- [ ] Team notified
-- [ ] Implementation tickets created
-- [ ] Related documentation updated
-```
-
-## Best Practices
-
-### Do's
-- **Write ADRs early** - Before implementation starts
-- **Keep them short** - 1-2 pages maximum
-- **Be honest about trade-offs** - Include real cons
-- **Link related decisions** - Build decision graph
-- **Update status** - Deprecate when superseded
-
-### Don'ts
-- **Don't change accepted ADRs** - Write new ones to supersede
-- **Don't skip context** - Future readers need background
-- **Don't hide failures** - Rejected decisions are valuable
-- **Don't be vague** - Specific decisions, specific consequences
-- **Don't forget implementation** - ADR without action is waste
-
-## Resources
-
-- [Documenting Architecture Decisions (Michael Nygard)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
-- [MADR Template](https://adr.github.io/madr/)
-- [ADR GitHub Organization](https://adr.github.io/)
-- [adr-tools](https://github.com/npryce/adr-tools)