swe-workflow-skills 0.1.0

package/skills/api-design/templates/api-spec.md

@@ -0,0 +1,156 @@
+# API Specification Template
+
+```markdown
+# [Service Name] API Specification
+
+**Version**: v1
+**Base URL**: `https://api.example.com/api/v1`
+**Authentication**: Bearer token (JWT)
+
+## Overview
+
+[Brief description of what this API provides and who consumes it.]
+
+## Authentication
+
+All endpoints except those marked as **Public** require a valid JWT in the Authorization header:
+
+```
+Authorization: Bearer <token>
+```
+
+## Common Conventions
+
+- All timestamps are ISO 8601 in UTC
+- All IDs are [format: UUID/ULID/integer]
+- Pagination uses cursor-based paging with `cursor` and `limit` parameters
+- Errors follow the standard error response format
+
+## Error Format
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable description",
+    "details": []
+  }
+}
+```
+
+---
+
+## [Resource Name]
+
+### List [Resources]
+
+`GET /[resources]`
+
+**Authentication**: Required
+**Authorization**: [roles/permissions]
+
+**Query Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `cursor` | string | No | Pagination cursor |
+| `limit` | integer | No | Items per page (default: 20, max: 100) |
+| `status` | string | No | Filter by status |
+
+**Response**: `200 OK`
+```json
+{
+  "data": [
+    {
+      "id": "res_abc123",
+      "field": "value",
+      "created_at": "2025-03-05T14:30:00Z"
+    }
+  ],
+  "pagination": {
+    "next_cursor": "eyJpZCI6MTAwfQ",
+    "has_more": true
+  }
+}
+```
+
+---
+
+### Get [Resource]
+
+`GET /[resources]/:id`
+
+**Authentication**: Required
+
+**Response**: `200 OK`
+```json
+{
+  "data": {
+    "id": "res_abc123",
+    "field": "value",
+    "created_at": "2025-03-05T14:30:00Z"
+  }
+}
+```
+
+**Errors**: `404 Not Found`
+
+---
+
+### Create [Resource]
+
+`POST /[resources]`
+
+**Authentication**: Required
+**Authorization**: [roles/permissions]
+
+**Request Body:**
+```json
+{
+  "field": "value",
+  "other_field": "value"
+}
+```
+
+| Field | Type | Required | Validation |
+|-------|------|----------|------------|
+| `field` | string | Yes | Max 255 characters |
+| `other_field` | string | No | Must be one of: [values] |
+
+**Response**: `201 Created`
+
+**Errors**: `400 Validation Error`, `409 Conflict`
+
+---
+
+### Update [Resource]
+
+`PATCH /[resources]/:id`
+
+**Authentication**: Required
+**Authorization**: [Owner or Admin]
+
+**Request Body:** (partial — only include fields to update)
+```json
+{
+  "field": "new value"
+}
+```
+
+**Response**: `200 OK`
+
+**Errors**: `400 Validation Error`, `404 Not Found`
+
+---
+
+### Delete [Resource]
+
+`DELETE /[resources]/:id`
+
+**Authentication**: Required
+**Authorization**: [Owner or Admin]
+
+**Response**: `204 No Content`
+
+**Errors**: `404 Not Found`
+```

package/skills/architecture-design/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: architecture-design
+description: "Guide architectural and structural decisions using Architecture Decision Records (ADRs) — new services, pattern choices, database selection, component boundaries, state management, costly-to-reverse decisions. Triggers: how should I architect, which pattern, design decision, should I use X or Y, system design, ADR, component design, architectural trade-off."
+model: opus
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Architecture Design
+
+Help the user make well-reasoned architectural decisions and document them in Architecture Decision Records (ADRs). Good architecture is about managing trade-offs explicitly, not finding perfect solutions.
+
+## Workflow
+
+### Step 1: Frame the Decision
+
+Identify the exact decision to be made. A good architectural question is specific and scoped:
+
+- **Too broad**: "How should I design the backend?"
+- **Right scope**: "Should user authentication be a separate microservice or a module within the monolith?"
+
+If the user's question is too broad, help narrow it by asking:
+- What triggered this decision? (new feature, scaling issue, tech debt)
+- What are the constraints? (team size, timeline, existing stack)
+- What's the blast radius? (which parts of the system are affected)
+
+### Step 2: Explore the Context
+
+Understand the current state before proposing changes:
+
+- **Current architecture**: What exists today? Read the codebase if available.
+- **Quality attributes that matter**: Performance? Scalability? Developer experience? Maintainability? Deployment simplicity?
+- **Team context**: Team size, expertise, on-call burden
+- **Growth trajectory**: Expected scale in 6-12 months (not 5 years — YAGNI)
+
+### Step 3: Generate Options
+
+Present 2-4 viable options. For each option:
+
+1. **Name it clearly** (e.g., "Separate Auth Service" vs "Auth Module in Monolith")
+2. **Describe the approach** in 2-3 sentences
+3. **Analyze trade-offs** against the quality attributes identified in Step 2
+4. **Estimate complexity** (implementation effort, operational overhead)
+5. **Identify reversibility** — how hard is it to change this decision later?
+
+Avoid presenting a straw-man option just to make the preferred one look better.
+
+### Step 4: Apply Design Principles
+
+Evaluate each option through these lenses:
+
+- **KISS**: Which option is simplest to implement and operate?
+- **YAGNI**: Which avoids building for hypothetical future needs?
+- **Functional Independence**: Which gives the cleanest boundaries and lowest coupling?
+- **Separation of Concerns**: Which isolates responsibilities clearly?
+- **DRY**: Which avoids duplication of logic or data?
+- **SOLID**: Does the design respect Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion? See [references/solid-principles.md](references/solid-principles.md).
+- **Clean Architecture**: Does the dependency direction point inward? Are business rules protected from infrastructure details? See [references/clean-architecture.md](references/clean-architecture.md).
+- **Component boundaries**: Are components cohesive (CCP, CRP) and acyclic (ADP)? Do dependencies flow toward stability (SDP)? See [references/component-principles.md](references/component-principles.md).
+
+Document which principles favor which option. Conflict between principles is expected — that's why it's a decision, not a formula.
+
+See [references/principles.md](references/principles.md) for deeper guidance on applying KISS, YAGNI, coupling, and separation of concerns to architecture decisions.
+
+### Step 5: Make a Recommendation
+
+State the recommended option clearly, with reasoning. Structure it as:
+
+1. **Recommendation**: Option X
+2. **Primary reason**: The most compelling argument (one sentence)
+3. **Key trade-off accepted**: What you're giving up and why it's acceptable
+4. **Conditions that would change this decision**: Future triggers to revisit
+
+### Step 6: Document the ADR
+
+Produce an ADR using the template at [templates/adr.md](templates/adr.md). Save it in the project's decision log (e.g., `docs/decisions/NNN-decision-title.md`).
+
+ADRs are immutable records. If a decision is superseded, create a new ADR that references the old one — don't edit the original.
+
+For visual architecture documentation (system diagrams, runtime flows, infrastructure topology), see the `architecture-documentation` skill.
+
+## When to Split Decisions
+
+If the analysis reveals multiple independent decisions bundled together, split them into separate ADRs. For example, "How should we handle caching?" might split into:
+- ADR-001: Cache invalidation strategy
+- ADR-002: Cache storage technology
+- ADR-003: Cache warming approach

package/skills/architecture-design/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "architecture-design",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We're building a SaaS platform and need to decide whether to use a multi-tenant single database or database-per-tenant approach. We have about 50 customers now, expecting 500 in a year. It's a Django app on PostgreSQL. Some customers are enterprise with strict data isolation requirements.",
+      "expected_output": "A structured analysis with at least 3 options (shared DB with row-level security, schema-per-tenant, DB-per-tenant), trade-off analysis against quality attributes, a clear recommendation with rationale, and an ADR document.",
+      "assertions": [
+        "Presents at least 3 distinct options",
+        "Analyzes trade-offs for each option (not just pros/cons lists)",
+        "Considers the enterprise data isolation requirement explicitly",
+        "Applies KISS and YAGNI (doesn't over-engineer for 500 customers)",
+        "Makes a clear recommendation with primary reason stated",
+        "Includes revisit triggers for when to reconsider",
+        "Produces an ADR document saved to the filesystem"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "should we use graphql or rest for our new api? we're a team of 3",
+      "expected_output": "Should ask clarifying questions first (what kind of clients, data complexity, team's GraphQL experience), then produce a balanced analysis that considers team size heavily.",
+      "assertions": [
+        "Asks clarifying questions before recommending",
+        "Considers team size (3 devs) as a major constraint",
+        "Applies KISS principle favoring simplicity for small team",
+        "Does not present a straw-man option",
+        "Identifies reversibility of the decision"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Our monolithic Rails app is getting slow and hard to deploy. The CTO wants to move to microservices. I'm not sure it's the right call. We have 12 developers and the app has about 200K lines of code. What should we do?",
+      "expected_output": "Should explore whether the problem is actually about microservices or about other improvements. Present options including modular monolith, selective extraction, and full microservices. Should be skeptical of a full rewrite.",
+      "assertions": [
+        "Does not immediately agree with 'move to microservices'",
+        "Explores root causes of slowness and deployment pain",
+        "Presents modular monolith as a viable option",
+        "Analyzes the distributed monolith anti-pattern risk",
+        "Considers team size relative to service count",
+        "References functional independence principle"
+      ]
+    }
+  ]
+}

package/skills/architecture-design/references/clean-architecture.md

@@ -0,0 +1,147 @@
+# Clean Architecture Reference
+
+## Contents
+- The Dependency Rule
+- The four layers
+- Screaming Architecture
+- Plugin Architecture
+- The Main Component
+- Humble Object Pattern
+- Policy and Level
+- Entities vs Use Cases
+- Crossing boundaries
+
+## The Dependency Rule
+
+**Source code dependencies must point inward only.** Nothing in an inner circle can know anything about something in an outer circle — not a name, a type, a function, or even that an outer layer exists.
+
+This is the foundational rule. Every other concept in Clean Architecture exists to enforce or support it. When dependencies point inward, the core business logic is protected from changes to UI, databases, frameworks, and delivery mechanisms.
+
+Data can flow outward (a use case returns a result to a controller), but the source code dependency still points inward — the outer layer calls into the inner layer, not the reverse. When inner layers need to communicate outward, they define an interface that the outer layer implements (Dependency Inversion Principle).
+
+## The Four Layers
+
+From innermost to outermost:
+
+### Layer 1: Entities
+Enterprise-wide business rules — the most general, highest-level policies. Entities encapsulate the critical business logic that would exist even if there were no software system.
+
+- Pure domain objects with behavior and validation
+- No dependency on any framework, database, or delivery mechanism
+- Reusable across applications (if the enterprise has multiple apps)
+- Example: `Order` that enforces "cannot add items after checkout", `Money` that handles currency arithmetic
+
+### Layer 2: Use Cases (Application Business Rules)
+Application-specific business rules that orchestrate entities to achieve a goal. Each use case represents one thing the system does for a user or external system.
+
+- Orchestrate the flow of data to and from entities
+- Contain application logic: "when user places order, validate stock, calculate total, reserve inventory, send confirmation"
+- Define input/output port interfaces (what data comes in, what goes out)
+- Independent of UI, database, or external services
+- Example: `PlaceOrderUseCase` that coordinates `Order`, `Inventory`, and `PaymentGateway` interfaces
+
+### Layer 3: Interface Adapters
+Convert data between the format used by use cases/entities and the format used by external agencies.
+
+- **Controllers**: Receive external input (HTTP, CLI, events), convert to use case input format, invoke the use case
+- **Presenters**: Take use case output, format it for the delivery mechanism (JSON, HTML, CLI output)
+- **Gateways**: Implement repository/service interfaces defined by use cases, translate to database queries or API calls
+- **DTOs**: Data transfer objects that cross the boundary — simple data structures, no business logic
+
+### Layer 4: Frameworks & Drivers
+The outermost layer — databases, web frameworks, UI frameworks, external APIs, file systems.
+
+- Contains no business logic — only glue code
+- Frameworks are kept at arm's length — they are tools, not the architecture
+- This layer is where the "details" live: which database, which web framework, which messaging system
+- Easiest to replace because nothing depends on it
+
+## Screaming Architecture
+
+**Your architecture should tell you what the system does, not what framework it uses.**
+
+When you look at a project's top-level directory structure, it should scream "healthcare system" or "accounting application" — not "Rails app" or "Spring Boot project."
+
+Signs of screaming architecture:
+- Top-level directories named after domain concepts: `orders/`, `inventory/`, `payments/`
+- Use cases are visible as first-class code artifacts, not buried inside controllers
+- You can understand the system's purpose without knowing the technology stack
+
+Signs of framework-dominated architecture:
+- Top-level directories named `controllers/`, `models/`, `views/`, `services/`
+- Business logic scattered across framework-specific classes
+- Switching frameworks would require rewriting business logic
+
+This doesn't mean you can't have a `controllers/` directory — but it should live inside a feature module, not the other way around.
+
+## Plugin Architecture
+
+**Frameworks, databases, and UI are plugins to the business rules — not the other way around.**
+
+The business rules are the core. Everything else plugs into them. This means:
+- The database is a plugin — you should be able to swap PostgreSQL for MongoDB without touching business logic
+- The web framework is a plugin — you should be able to swap Express for Fastify without touching use cases
+- The UI is a plugin — you should be able to add a CLI interface alongside the web UI without duplicating logic
+
+This is achieved through interfaces defined by the inner layers and implemented by the outer layers (DIP).
+
+## The Main Component
+
+Every application has an entry point — `main()`, `app.ts`, `settings.py`. This is the "dirtiest" component in the system:
+
+- It knows about everything: frameworks, databases, use cases, entities
+- It wires all the dependencies together (composition root)
+- It is a plugin to the application — the outermost detail
+- It should contain no business logic — only wiring
+
+The Main component is where dependency injection configuration lives. It creates concrete implementations and passes them to the layers that depend on abstractions.
+
+## Humble Object Pattern
+
+**Separate behaviors that are hard to test from behaviors that are easy to test.**
+
+At every architectural boundary, you'll find code that's hard to test (UI rendering, database I/O, network calls) adjacent to code that's easy to test (data formatting, validation, business decisions). The Humble Object pattern splits them:
+
+- **Humble part**: Kept as simple as possible. Does the hard-to-test thing (renders HTML, executes SQL) but contains no logic worth testing.
+- **Testable part**: Contains all the decisions and logic. Receives and returns simple data structures.
+
+Common applications:
+- **Presenter / View**: The presenter formats data and makes decisions (testable). The view just renders what the presenter provides (humble).
+- **Gateway / Database**: The gateway implementation executes queries (humble). The use case that calls the gateway interface contains the logic (testable).
+- **Controller / Framework**: The framework routing is humble. The controller logic that processes input is testable.
+
+## Policy and Level
+
+Software is composed of policies at different levels. High-level policies (business rules) change rarely and for important reasons. Low-level policies (formatting, I/O, protocols) change frequently and for trivial reasons.
+
+The architecture should protect high-level policies from changes to low-level details:
+- Business rules should not change when you switch databases
+- Domain logic should not change when you change the API response format
+- Core calculations should not change when you add a new delivery channel
+
+**Level** is determined by distance from inputs and outputs. The farther a policy is from I/O, the higher its level. Entities are the highest level; UI rendering and database queries are the lowest.
+
+## Entities vs Use Cases
+
+This distinction is often confused. The key difference:
+
+**Entities** embody enterprise-wide business rules that exist independently of any application:
+- "An order must have at least one line item"
+- "Discount cannot exceed 50% of the item price"
+- "A user's email must be unique"
+
+**Use Cases** embody application-specific rules that orchestrate entities:
+- "When a user places an order: validate stock, apply discount rules, calculate shipping, charge payment, send confirmation"
+- "When an admin cancels an order: refund payment, restore stock, notify user"
+
+Entities don't know about use cases. Use cases know about entities and direct them to enforce their rules.
+
+## Crossing Boundaries
+
+When data crosses an architectural boundary:
+- Use simple data structures (DTOs, value objects) — not entity objects or framework objects
+- The inner layer defines what it needs (input port) and what it returns (output port)
+- The outer layer maps its own data structures to/from the boundary's format
+- Never pass database rows or HTTP request objects into business logic
+
+This keeps each layer independent and testable. The mapping code lives in the Interface Adapters layer.

package/skills/architecture-design/references/component-principles.md

@@ -0,0 +1,129 @@
+# Component Principles Reference
+
+## Contents
+- Component cohesion (REP, CCP, CRP)
+- Component coupling (ADP, SDP, SAP)
+- The tension triangle
+- Stability and abstractness metrics
+
+Components are the units of deployment — JARs, gems, npm packages, Go modules, Python packages. These principles guide what goes into a component and how components relate to each other.
+
+## Component Cohesion Principles
+
+These three principles govern which classes belong together in a component. They pull in different directions — balancing them is a design judgment.
+
+### Reuse/Release Equivalence Principle (REP)
+
+**The granule of reuse is the granule of release.**
+
+Classes and modules that are reused together should be released together, with a shared version number and release process. If you release a component, everything in it should make sense to a consumer who depends on it.
+
+Violation signals:
+- A package where consumers only use 20% of the classes and are forced to take the other 80%
+- A "utils" package with unrelated utilities — date formatting, string helpers, HTTP clients, and logging all in one
+- Version bumps that break consumers who don't use the changed code
+
+### Common Closure Principle (CCP)
+
+**Gather together classes that change for the same reasons and at the same time.**
+
+This is SRP at the component level. A change in requirements should affect one component, not scatter across many. When classes change together, they belong together.
+
+This minimizes the number of components that need to be redeployed when a requirement changes.
+
+Violation signals:
+- A single feature change requires modifying 5+ components
+- Related classes are scattered across packages by technical layer rather than grouped by business capability
+- Every PR touches the same set of "shared" packages
+
+### Common Reuse Principle (CRP)
+
+**Don't force users of a component to depend on things they don't need.**
+
+If a consumer uses one class from a component, it implicitly depends on the entire component. If another class in that component changes, the consumer must revalidate and potentially redeploy — even though it doesn't use the changed class.
+
+This is ISP at the component level.
+
+Violation signals:
+- Consumers frequently pinpoint specific files to import rather than using the component as a whole
+- A change to an unused class in a dependency forces downstream rebuilds or version bumps
+- "I only need the `parseDate` function but I have to install a 2MB package"
+
+## The Tension Triangle
+
+REP, CCP, and CRP pull in different directions:
+
+```
+        REP
+       /    \
+     CCP --- CRP
+```
+
+- **REP + CCP** (group for reusers + group for changers): Tends toward large components — easy to release and change together, but consumers depend on more than they need (violates CRP)
+- **CCP + CRP** (group for changers + split for consumers): Tends toward many small components — changes are localized and consumers only get what they need, but hard to manage releases (violates REP)
+- **REP + CRP** (group for reusers + split for consumers): Tends toward well-packaged components, but changes scatter across many of them (violates CCP)
+
+**Early in a project**, favor CCP — you want changes localized because requirements shift fast. **As the project matures and gains consumers**, shift toward REP and CRP — reusability and minimal dependency surface matter more.
+
+## Component Coupling Principles
+
+These three principles govern the dependency relationships between components.
+
+### Acyclic Dependencies Principle (ADP)
+
+**The dependency graph of components must have no cycles.**
+
+Cycles create a "morning after" problem: you arrive to find your code broken because something you depend on changed, which depended on something you changed, creating an unresolvable build order.
+
+With cycles:
+- You cannot build or test components in isolation
+- A change anywhere in the cycle potentially affects everything in the cycle
+- Release order becomes ambiguous or impossible
+
+How to break cycles:
+1. **Apply DIP**: If A depends on B and B depends on A, have B depend on an interface defined by A (or introduce a new component for the shared abstraction)
+2. **Extract a new component**: Move the shared dependency into its own component that both A and B depend on
+3. **Merge the components**: If two components are so intertwined they form a cycle, they may actually be one component
+
+### Stable Dependencies Principle (SDP)
+
+**Depend in the direction of stability.**
+
+A component's stability is measured by how hard it is to change. Components that many others depend on are stable (changing them has high cost). Components with few dependents are volatile (easy to change).
+
+**Stability metric (I)**: `I = Fan-out / (Fan-in + Fan-out)`
+- Fan-in: number of incoming dependencies (other components that depend on this one)
+- Fan-out: number of outgoing dependencies (components this one depends on)
+- I = 0: maximally stable (everyone depends on it, it depends on nothing)
+- I = 1: maximally unstable (it depends on others, nobody depends on it)
+
+The rule: a component should only depend on components with a lower I (more stable). Depending on something less stable than yourself means your component can be destabilized by volatile changes.
+
+### Stable Abstractions Principle (SAP)
+
+**A component should be as abstract as it is stable.**
+
+Stable components (hard to change because many depend on them) should consist of abstractions — interfaces and abstract classes — so they can be extended without modification (OCP).
+
+Volatile components (easy to change) should be concrete — they contain the implementation details that change frequently.
+
+**Abstractness metric (A)**: `A = abstract classes and interfaces / total classes`
+- A = 0: fully concrete (no abstractions)
+- A = 1: fully abstract (only interfaces)
+
+Plotting I against A gives the **Main Sequence** — the ideal diagonal where `I + A ≈ 1`:
+- Components near (0,1): stable and abstract — good (e.g., interface packages)
+- Components near (1,0): volatile and concrete — good (e.g., implementations, UI)
+- Components near (0,0): stable and concrete — **Zone of Pain** (hard to change but contains implementation details)
+- Components near (1,1): volatile and abstract — **Zone of Uselessness** (abstract but nobody depends on it)
+
+## Applying These Principles
+
+When designing component boundaries:
+
+1. **Start with CCP** — group by business capability so changes are localized
+2. **Check for cycles (ADP)** — if you find one, restructure using DIP or extraction
+3. **Verify stability direction (SDP)** — volatile components should not be depended upon by stable ones
+4. **Balance abstraction with stability (SAP)** — if a component is heavily depended upon, make it abstract
+5. **As consumers appear, apply CRP** — split components so consumers only depend on what they use
+6. **Version and release cohesive units (REP)** — everything in a release should make sense together

package/skills/architecture-design/references/principles.md

@@ -0,0 +1,81 @@
+# Architecture Principles Reference
+
+## Contents
+- KISS in architecture
+- YAGNI in architecture
+- Functional independence and coupling
+- Separation of concerns
+- DRY at the system level
+- Common anti-patterns
+
+## KISS in Architecture
+
+Simplicity in architecture means fewer moving parts, fewer failure modes, and faster onboarding. When evaluating options:
+
+- Prefer a monolith over microservices unless you have a concrete scaling or deployment bottleneck that a monolith cannot solve
+- Prefer synchronous communication unless you need resilience to downstream failures
+- Prefer a single database unless you have conflicting access patterns that provably degrade each other
+- Prefer server-side rendering unless you need offline capability or real-time interactivity
+
+The burden of proof is on complexity — if you can't articulate why the simpler approach fails, choose simple.
+
+## YAGNI in Architecture
+
+Build for today's known requirements plus 6 months of projected growth. Do not:
+
+- Design for "millions of users" when you have hundreds
+- Add a message queue because "we might need it"
+- Create microservices because "we might scale the team"
+- Abstract every boundary because "we might swap implementations"
+
+Instead, identify the minimum viable architecture that meets current quality attributes. Document what triggers a redesign (e.g., "if request latency exceeds 200ms at P95, revisit the caching strategy").
+
+## Functional Independence and Coupling
+
+Measure coupling by asking: "If I change module A, how many other modules must also change?"
+
+Coupling types (ordered from worst to best):
+1. **Content coupling**: Module A directly modifies the internals of module B
+2. **Common coupling**: Modules share global mutable state
+3. **Control coupling**: Module A passes flags that dictate module B's behavior
+4. **Stamp coupling**: Modules share composite data structures but only use parts
+5. **Data coupling**: Modules share only the data they each need (best achievable)
+
+At the architecture level, aim for data coupling between services/modules. Each component should have a well-defined interface and no knowledge of other components' internals.
+
+## Separation of Concerns
+
+Good boundaries emerge from asking "what changes together?":
+
+- **Business rules** change when business requirements change
+- **Data access** changes when storage technology changes
+- **Presentation** changes when UX requirements change
+- **Infrastructure** changes when deployment targets change
+
+If a single change requires touching all four layers, your separation is leaking. Common signs:
+- Business logic inside API controllers
+- SQL queries inside domain models
+- Formatting logic inside data access layers
+- Environment-specific code outside configuration
+
+## DRY at the System Level
+
+DRY in architecture is about eliminating **knowledge duplication**, not code duplication. Two services can have similar code if they represent different business concepts that happen to look alike today.
+
+Dangerous false DRY:
+- Sharing a "common" library between services that evolve at different rates
+- Creating a "generic" service that handles too many concerns
+- Forcing different domains into a shared data model
+
+Legitimate DRY:
+- Centralizing authentication/authorization logic
+- Shared API contracts (OpenAPI specs, protobuf definitions)
+- Common infrastructure configuration (Terraform modules, Helm charts)
+
+## Common Anti-patterns
+
+- **Premature abstraction**: Creating interfaces and abstractions before you have two concrete implementations
+- **Distributed monolith**: Microservices that must be deployed together and share a database
+- **God service**: One service that everything depends on and that handles too many concerns
+- **Speculative generality**: Building for flexibility nobody has asked for
+- **Golden hammer**: Using the same pattern/technology for every problem