add beyond

11 files changed, 1039 insertions, 0 deletions

diff --git a/prompts/skills/beyond-solid-principles/SKILL.md b/prompts/skills/beyond-solid-principles/SKILL.md
new file mode 100644
index 0000000..3300966
--- /dev/null
+++ b/prompts/skills/beyond-solid-principles/SKILL.md
@@ -0,0 +1,150 @@
+---
+name: beyond-solid-principles
+version: 1.0.0
+description: >
+  This skill should be used when the user asks to "check architecture principles",
+  "audit system design", "review code for coupling", "find architecture smells", or
+  "improve system-level design". Also triggers when the user mentions a principle by
+  name (e.g., "check separation of concerns", "is this violating DRY?", "Law of
+  Demeter", "KISS", "YAGNI", "resilience", "evolvability", "loose coupling"). Supports
+  checking all ten principles at once or focusing on a single principle.
+---
+
+# Beyond SOLID — System-Level Architecture Principles
+
+Analyze source code and system architecture for violations of ten foundational design
+principles that govern how modules, services, layers, and components are structured
+and interact. Produce actionable findings with severity ratings, code/architecture
+locations, and concrete remediation suggestions.
+
+These principles operate at the architecture scale — modules, services, bounded
+contexts, layers, APIs — complementing the class-level SOLID principles.
+
+## Subcommands
+
+Request a full audit or focus on a single principle:
+
+| Command Pattern | Principle | Reference |
+|----------------|-----------|-----------|
+| `sw-soc` | Separation of Concerns | `references/soc.md` |
+| `sw-srp-sys` | Single Responsibility (system-level) | `references/srp-sys.md` |
+| `sw-dry` | Don't Repeat Yourself (DRY) | `references/dry.md` |
+| `sw-demeter` | Law of Demeter / Principle of Least Knowledge | `references/demeter.md` |
+| `sw-coupling` | Loose Coupling, High Cohesion | `references/coupling.md` |
+| `sw-evolvability` | Build for Change (Evolvability) | `references/evolvability.md` |
+| `sw-resilience` | Design for Failure / Resilience | `references/resilience.md` |
+| `sw-kiss` | KISS — Keep It Simple | `references/kiss.md` |
+| `sw-pola` | Principle of Least Surprise (POLA) | `references/pola.md` |
+| `sw-yagni` | YAGNI at Architecture Level | `references/yagni.md` |
+| `beyond-solid-principles` | All ten principles | All references |
+
+When no subcommand is specified, default to checking all ten principles.
+When a principle is mentioned by name (even without the command prefix), match it to
+the appropriate subcommand.
+
+## Workflow
+
+### 1. Identify Target Code
+
+Determine what code or architecture to analyze:
+- When files or a directory are provided, use those.
+- When a service, module, or component is referenced by name, locate it.
+- When ambiguous, ask which files, directories, or services to scan.
+
+These principles apply to any language and any architecture style — monoliths,
+modular monoliths, microservices, serverless, event-driven, layered, hexagonal, etc.
+Adapt the principle checks to the idioms and scale of the target system.
+
+For smaller codebases, focus on module/package boundaries, dependency direction,
+and internal layering. For distributed systems, also consider service boundaries,
+API contracts, data ownership, messaging patterns, and operational resilience.
+
+### 2. Load Principle References
+
+Before analyzing, read the reference file(s) for the requested principle(s):
+
+- [`references/soc.md`](references/soc.md) for Separation of Concerns
+- [`references/srp-sys.md`](references/srp-sys.md) for Single Responsibility (system-level)
+- [`references/dry.md`](references/dry.md) for DRY
+- [`references/demeter.md`](references/demeter.md) for Law of Demeter
+- [`references/coupling.md`](references/coupling.md) for Loose Coupling, High Cohesion
+- [`references/evolvability.md`](references/evolvability.md) for Build for Change
+- [`references/resilience.md`](references/resilience.md) for Design for Failure
+- [`references/kiss.md`](references/kiss.md) for KISS
+- [`references/pola.md`](references/pola.md) for Principle of Least Surprise
+- [`references/yagni.md`](references/yagni.md) for YAGNI
+
+For a full audit (`beyond-solid-principles`), read all ten.
+
+### 3. Analyze
+
+For each target file, module, or service boundary, apply the violation patterns from
+the loaded references. Think carefully about each pattern — not every heuristic match
+is a true violation. Consider context, system scale, team size, and maturity.
+
+Key analysis dimensions:
+- **Static structure**: dependency direction, import graphs, layer boundaries.
+- **Change patterns**: which files/modules change together (if VCS history is available).
+- **Runtime topology**: service call chains, data flow, failure propagation paths.
+- **API contracts**: consistency, encapsulation, versioning, naming conventions.
+- **Operational posture**: timeouts, retries, circuit breakers, health checks.
+
+### 4. Report Findings
+
+Present findings using this structure:
+
+#### Per Violation
+
+```
+**[PRINCIPLE] Violation — Severity: HIGH | MEDIUM | LOW**
+Location: `filename` or `service/module`, lines ~XX-YY (if applicable)
+Issue: Clear description of what violates the principle and why it matters.
+Suggestion: Concrete remediation approach with brief code or architecture sketch if helpful.
+```
+
+Severity guidelines:
+- **HIGH**: Active maintenance pain, production risk, blocks independent evolution,
+  or causes cascading failures.
+- **MEDIUM**: Architecture smell that will cause problems as the system grows or
+  as more teams contribute.
+- **LOW**: Minor design impurity, worth noting but fine to defer.
+
+#### Summary
+
+After all findings, provide:
+- A count table: `| Principle | HIGH | MEDIUM | LOW |`
+- Top 3 priorities: which violations to fix first and why.
+- Overall assessment: one paragraph on the system's structural health and
+  evolvability posture.
+
+### 5. Refactor Mode (Optional)
+
+When a fix or refactoring is requested (e.g., "fix this", "refactor it",
+"show me the clean version"), produce refactored code or an architecture proposal
+that resolves the identified violations. Explain each change briefly.
+
+## Pragmatism Guidelines
+
+These are guidelines, not laws. Apply judgment:
+
+- Small projects and prototypes get a lighter touch. Don't flag a weekend project
+  for lacking circuit breakers or API versioning.
+- Some "violations" are conscious trade-offs. When a rationale is documented (e.g.,
+  in an ADR), acknowledge it rather than insisting on purity.
+- Scale matters. A single-service CRUD app does not need the same architectural rigor
+  as a platform serving millions of requests. Calibrate severity to context.
+- Principles have productive tensions. DRY conflicts with loose coupling across service
+  boundaries. KISS conflicts with resilience patterns. YAGNI conflicts with evolvability.
+  Flag the tension and offer judgment, not dogma.
+- Prefer actionable findings over exhaustive catalogs. Five important findings
+  beat twenty trivial ones.
+
+## Example Interaction
+
+**User**: `sw-coupling` (with a codebase directory)
+
+**Claude**:
+1. Reads `references/coupling.md`
+2. Analyzes the directory for coupling/cohesion violations
+3. Reports findings with locations, severity, and suggestions
+4. Provides a summary with priorities
diff --git a/prompts/skills/beyond-solid-principles/references/coupling.md b/prompts/skills/beyond-solid-principles/references/coupling.md
new file mode 100644
index 0000000..cb03f78
--- /dev/null
+++ b/prompts/skills/beyond-solid-principles/references/coupling.md
@@ -0,0 +1,84 @@
+# Loose Coupling, High Cohesion
+
+> "The goal is to create modules that can be understood, developed, tested, and maintained independently." — Larry Constantine & Ed Yourdon, Structured Design (1979)
+
+## Core Idea
+
+Larry Constantine and Ed Yourdon defined these complementary metrics in Structured Design (1979). Coupling measures how much one component depends on another's details; cohesion measures how related the elements within a single component are. The ideal is low coupling between components and high cohesion within them. Sam Newman calls this the core motivator behind microservices and event-driven architecture. Azure's microservices guidance: "microservices are loosely coupled if you can change one service without requiring other services to be updated at the same time, and cohesive if they have a single, well-defined purpose." At system scale, Martin's package coupling metrics provide quantitative tools: the Stable Dependencies Principle, the Stable Abstractions Principle, and the Distance from Main Sequence metric.
+
+## Violation Patterns
+
+### 1. Distributed Monolith
+
+**Heuristic:** Services that must deploy together despite being technically separate. Gremlin identifies three forms: behavioral coupling (dependency must be available), temporal coupling (requiring low-latency synchronous communication), and implementation coupling (changes to one service force changes in others).
+
+**Look for:**
+- Coordinated deployments are normal because changes require multiple services to update together
+- Inability to deploy services independently
+- Service A becomes unavailable when service B goes down
+
+**Refactoring/Remedy:** Redraw boundaries along business capabilities using DDD. Each service should own its data and be independently deployable. Use asynchronous messaging to eliminate temporal coupling.
+
+### 2. Shared Mutable State / Shared Database
+
+**Heuristic:** Multiple services read and write the same database schema, creating hidden coupling at the data layer.
+
+**Look for:**
+- Multiple services with direct access to the same tables
+- Schema changes requiring coordination across teams
+- "Using database entities as events" (Azure antipattern)
+- Modules sharing global caches or static singletons
+
+**Refactoring/Remedy:** Each service owns its data store with no cross-service database access. When Service B needs Service A's data, A publishes events and B maintains a local projection. Use Anti-Corruption Layers to protect boundaries.
+
+### 3. Synchronous Call Chain Entanglement
+
+**Heuristic:** Long synchronous dependency chains (A→B→C→D) where all services must be responsive simultaneously. This creates temporal coupling that cascades both latency and failure.
+
+**Look for:**
+- Distributed traces showing deep synchronous call chains
+- P95/P99 latencies compounding across hops
+- One slow service causing all upstream services to degrade
+- Thread pool exhaustion from blocked calls
+
+**Refactoring/Remedy:** Replace synchronous chains with asynchronous messaging (Kafka, RabbitMQ, SQS) where possible. Use event-driven patterns where services react to domain events rather than pulling data through call chains.
+
+### 4. Low Cohesion — Technical-Layer Organization
+
+**Heuristic:** Organizing by technical layer (/entities/, /factories/, /repositories/) rather than business domain produces low cohesion: a single feature change touches files across many folders.
+
+**Look for:**
+- Shotgun surgery — a feature change requires editing files in 5+ unrelated directories
+- Architecture diagrams that look like spaghetti with no clear dependency direction
+- "Common" or "Shared" projects with unrelated functionality mixed together (logging, date helpers, domain rules, UI utilities)
+
+**Refactoring/Remedy:** Organize by business capability and bounded context. Group operations that naturally change together into one cohesive module. Feature slicing: keep all code for one feature vertically aligned.
+
+### 5. Wide Interfaces Leaking Implementation Details
+
+**Heuristic:** Service interfaces become "wide" because other services need internal details, not because domain operations require them.
+
+**Look for:**
+- APIs that expose internal data structures rather than domain operations
+- Many endpoints/fields that exist for other services rather than domain needs
+- Interservice chattiness grows as teams spend effort managing call graphs
+- APIs that model internal implementation rather than the domain
+
+**Refactoring/Remedy:** Design APIs to model the domain, not internal implementation. Use intention-revealing operations (PlaceOrder, not SetOrderStatusAndUpdateInventoryAndNotifyShipping). Consumer-driven contract testing (Pact) verifies provider changes don't break consumer expectations.
+
+## System-Scale Notes
+
+- Martin's package coupling metrics: Afferent coupling (Ca) = inbound dependencies, Efferent coupling (Ce) = outbound dependencies. Instability (I = Ce/(Ca+Ce)). Distance from Main Sequence catches modules in the "Zone of Pain" (concrete but heavily depended upon) or "Zone of Uselessness" (abstract but unused).
+- Deployment coupling is the most practical smell — can you deploy services independently?
+- Git co-change analysis reveals logical coupling invisible in static dependency graphs.
+- Chaos engineering (injecting failures) tests whether services are truly independent.
+- Track Ca, Ce, and instability per module in CI pipelines as automated fitness functions.
+- CodeOpinion emphasizes functional cohesion (grouping by related business operations) over informational cohesion (grouping by shared data).
+- Destructive decoupling is the opposite extreme — decoupling so aggressively that interfaces everywhere have no coherent purpose.
+
+## False Positives to Avoid
+
+- Libraries or modules with high afferent coupling (many things depend on them) that are also highly stable and abstract are not violating coupling principles — they are in the ideal "Zone of the Main Sequence."
+- A service that makes several calls to another service as part of a single coherent operation is not necessarily too tightly coupled — evaluate whether the calls represent a genuinely distributed workflow.
+- Event-driven architecture still has coupling — it's just looser and temporal. Publishing an event doesn't eliminate the dependency; it changes its nature.
+- A well-designed monolith with clear module boundaries can have lower coupling than poorly-designed microservices.
diff --git a/prompts/skills/beyond-solid-principles/references/demeter.md b/prompts/skills/beyond-solid-principles/references/demeter.md
new file mode 100644
index 0000000..84b7a35
--- /dev/null
+++ b/prompts/skills/beyond-solid-principles/references/demeter.md
@@ -0,0 +1,82 @@
+# Principle of Least Knowledge / Law of Demeter
+
+> "Only talk to your immediate friends." — Ian Holland, Northeastern University, 1987
+
+## Core Idea
+
+The Law of Demeter states that a method may only invoke methods on itself, its parameters, objects it creates, and its instance variables — never on objects returned by other method calls. At architecture scale, LoD constrains communication patterns: a component should only interact with its immediate collaborators and never reach through them to access distant internal details. Robert C. Martin devotes several pages of Clean Code Chapter 6 to "Train Wrecks," "Hybrids," and "Hiding Structure." Martin Fowler pragmatically calls it the "Occasionally Useful Suggestion of Demeter." The key insight: LoD is a coupling-control rule that limits what components need to know about each other's internal structure.
+
+## Violation Patterns
+
+### 1. Train Wreck / Deep Object Navigation
+
+**Heuristic:** Chained method/property calls that traverse multiple objects, exposing deep structural knowledge.
+
+**Look for:**
+- `ctxt.getOptions().getScratchDir().getAbsolutePath()`
+- `order.getCustomer().getAddress().getCity()`
+- Chains longer than two dots on objects (not data structures)
+- Disguising chains with intermediate variables doesn't fix it — the caller still knows the internal structure
+
+**Refactoring/Remedy:** Apply "Tell, Don't Ask" — instead of querying an object's internals, tell the object what you need done. `account.withdraw(amount)` replaces interrogating the balance externally. Create intention-revealing methods that hide the navigation.
+
+### 2. Service Reach-Through / Transitive Dependencies
+
+**Heuristic:** Service A calls Service B, which calls Service C, giving A implicit knowledge of the B→C relationship. If C changes its API, both B and A may break.
+
+**Look for:**
+- Distributed traces showing call chains longer than one hop from a given service's perspective
+- A client service calling a downstream service then reaching through its DTOs to call another service
+- Multi-hop synchronous flows that tightly couple components
+
+**Refactoring/Remedy:** Use facade patterns and API gateways that aggregate calls so clients don't chain through services. Enforce that each layer calls only the layer directly below it.
+
+### 3. Schema Reach-Through in Service Architectures
+
+**Heuristic:** A service reads another service's internal tables, internal event payloads, or database entities directly — coupling itself to the other service's internal representation.
+
+**Look for:**
+- Services reading each other's database tables
+- Integration tests that manipulate internal tables or queues of a service instead of using its public interface
+- Azure explicitly calls "using database entities as events" an antipattern because it exposes internal details
+
+**Refactoring/Remedy:** Enforce "database per service." Services communicate only through public APIs or published events. Event payloads should represent domain concepts, not internal database entities.
+
+### 4. Client-Side Business Logic / Orchestrator Overreach
+
+**Heuristic:** UI clients, API gateways, or orchestrator services replicate domain rules that should live behind service boundaries, effectively knowing too much about the internal logic of services.
+
+**Look for:**
+- Gateway/orchestrator code that queries multiple contexts and recomputes internal state
+- Calling code that depends on deep internal fields of complex DTOs that should be encapsulated
+- Clients assembling a domain operation by pulling many internal fields because no coherent "tell" operation exists
+
+**Refactoring/Remedy:** Expose narrow, intention-revealing APIs (PlaceOrder, ReserveInventory) instead of leaking raw data for callers to manipulate. Push domain logic into the service that owns the bounded context.
+
+### 5. Layer Skipping
+
+**Heuristic:** Presentation layer directly calls data access, bypassing business logic. Lower layers reach up to higher layers.
+
+**Look for:**
+- UI code directly executing SQL or calling repository methods
+- Infrastructure modules importing from service/domain modules
+- Circular imports or lazy imports used to work around circular dependencies
+
+**Refactoring/Remedy:** Enforce strict layer dependency direction. Higher layers call lower layers only through defined interfaces. Use dependency inversion to break circular dependencies.
+
+## System-Scale Notes
+
+- Robert C. Martin draws an important distinction: data structures (DTOs, records) expose data with no behavior — navigating through them is acceptable. Objects expose behavior and hide data — chaining through objects violates LoD.
+- Builder patterns and fluent APIs that return the same type at each step are explicitly not violations.
+- The Response For a Class (RFC) metric — methods potentially invoked in response to a method call — correlates with bug probability. Following LoD reduces RFC.
+- Coupling Between Objects (CBO) measures how many external types a class references.
+- At architecture level, visualize service-to-service call chains: any path longer than one hop suggests a potential violation.
+- The Demeter paper notes that LoD tends to force narrow method-level dependencies but can lead to wide class-level interfaces because you introduce auxiliary methods rather than digging into structures. This trade-off requires system-level judgment.
+- JetBrains IntelliJ includes a built-in "Law of Demeter" inspection.
+
+## False Positives to Avoid
+
+- Navigating through data structures (DTOs, records, configuration objects) is acceptable — LoD applies to objects with behavior, not plain data.
+- Fluent APIs and builder patterns that return `this` or the same builder type are not violations — the chain stays on one object.
+- A facade that deliberately aggregates multiple calls behind a single interface is not a violation — it's the recommended fix.
+- Standard library traversals (e.g., `path.parent.name` in pathlib, or stream operations) are generally not violations.
diff --git a/prompts/skills/beyond-solid-principles/references/dry.md b/prompts/skills/beyond-solid-principles/references/dry.md
new file mode 100644
index 0000000..0fac87e
--- /dev/null
+++ b/prompts/skills/beyond-solid-principles/references/dry.md
@@ -0,0 +1,79 @@
+# Don't Repeat Yourself (DRY)
+
+> "Every piece of knowledge must have a single, unambiguous, authoritative representation within a system." — Andy Hunt & Dave Thomas, The Pragmatic Programmer (1999)
+
+## Core Idea
+
+DRY is about knowledge, not code. Two identical-looking code blocks representing different domain concepts are incidental duplication — merging them creates harmful coupling. Two different-looking blocks encoding the same business rule are the real violation. At architecture scale, the most dangerous violation is either (a) the same business rule implemented independently in multiple services leading to divergence, or (b) shared domain-object libraries that create distributed monoliths. Sam Newman: "The evils of too much coupling between services are far worse than the problems caused by code duplication." DRY has two distinct failure modes: under-DRY (true duplication of the same knowledge across components) and overzealous-DRY (premature centralization that creates coupling).
+
+## Violation Patterns
+
+### 1. Divergent Business Rules Across Services
+
+**Heuristic:** The same business rule (pricing, validation, eligibility, authorization) is independently encoded in multiple services without a shared authoritative source.
+
+**Look for:**
+- Password validation enforced as 8 chars in web, 10 in mobile, 6 on backend
+- Discount logic repeated in web app, mobile API, and reporting ETL
+- A single business rule change requiring modifications in multiple services (shotgun surgery)
+
+**Refactoring/Remedy:** Identify the authoritative owner of each business rule. Centralize within the owning bounded context. Other consumers call the owner's API or subscribe to its events rather than re-implementing the rule.
+
+### 2. Schema and Contract Divergence
+
+**Heuristic:** Multiple services expose subtly different representations of the same concept because each defined it ad-hoc.
+
+**Look for:**
+- "Customer" looks different across services and databases without a clear reason
+- JSON fields with same meaning but different names (userId vs customer_id)
+- Multiple, slightly different API definitions for the same entity creating integration friction
+
+**Refactoring/Remedy:** Use contract-first design (OpenAPI, Protobuf, AsyncAPI) to generate clients and servers from a single source of truth. Establish canonical models for cross-cutting concepts and version them carefully.
+
+### 3. Shared Library Coupling (Overzealous DRY)
+
+**Heuristic:** A shared domain-object library forces all consuming services to update simultaneously whenever a field changes.
+
+**Look for:**
+- Many services cannot upgrade independently because a shared library or shared schema change forces widespread rebuild/redeploy
+- Shared entity libraries that grow to include domain logic specific to individual services
+- Azure warns "sharing common libraries" is a coupling antipattern
+
+**Refactoring/Remedy:** Share stable contracts (published interfaces), not implementations. Prefer duplication of domain-specific models across bounded contexts over shared libraries. Sam Newman: lean toward duplication when unsure.
+
+### 4. Shared Database as Integration Point
+
+**Heuristic:** Multiple services reading and writing the same database schema, using the database as an implicit integration contract.
+
+**Look for:**
+- Multiple services with direct access to the same tables
+- Schema changes requiring coordination across teams
+- The database schema is treated as shared mutable state
+
+**Refactoring/Remedy:** Each service owns its data store. Integrate through APIs or events, not shared databases. Use materialized views or local copies for read-heavy cross-service data needs.
+
+### 5. Infrastructure Pattern Duplication
+
+**Heuristic:** Each service independently implements its own logging format, retry logic, idempotency strategy, health checks, and configuration management.
+
+**Look for:**
+- Copy-pasted HTTP client setup, message deserialization, logging and correlation logic across services
+- Different copies of connection strings and feature flags hardcoded in multiple services
+- Bug fixes that must be applied in many places
+
+**Refactoring/Remedy:** Extract genuinely cross-cutting infrastructure into shared libraries or sidecars. Use centralized config services (Consul, Vault, Azure App Configuration). Standardize via service mesh for network-level concerns.
+
+## System-Scale Notes
+
+- **The Rule of Three:** Don't abstract until you see three instances of the same knowledge — by the third you understand the commonality well enough. Sandi Metz: "It is better to have some duplication than a bad abstraction."
+- **Strategic approach:** Apply DRY aggressively within bounded contexts but accept duplication across them.
+- Share stable, cross-cutting types (like a PostalCode value object) but duplicate domain-specific models (like Address, which will diverge between Billing and Delivery).
+- **Fowler's Harvested Platform pattern:** don't build shared infrastructure upfront. Build well-factored applications, notice duplication, and extract shared code only after patterns stabilize.
+- Static analysis tools (SonarQube, CPD) detect syntactic duplication but cannot identify knowledge duplication. Treat their findings as investigation triggers, not mandates. The key question: "Is this knowledge duplication or syntactic similarity?"
+
+## False Positives to Avoid
+
+- Having a Customer class in both Checkout and OrderManagement microservices is proper bounded-context separation, not a DRY violation — each representation will diverge to serve its context.
+- Two code blocks that look identical but represent different domain concepts (e.g., tax calculation for two jurisdictions that happen to currently have the same rate) are incidental duplication — merging them would create harmful coupling.
+- Boilerplate required by a framework (e.g., controller setup, DI wiring) is not a DRY violation — it's structural scaffolding.
+- Configuration that differs per environment (dev/staging/prod) is not duplication — it's intentional variation.
diff --git a/prompts/skills/beyond-solid-principles/references/evolvability.md b/prompts/skills/beyond-solid-principles/references/evolvability.md
new file mode 100644
index 0000000..1fb7fb1
--- /dev/null
+++ b/prompts/skills/beyond-solid-principles/references/evolvability.md
@@ -0,0 +1,87 @@
+# Build for Change (Evolvability)
+
+> "Prefer evolvable over predictable — optimize for responding to unknown challenges rather than perfectly solving known ones." — Ford, Parsons & Kua, Building Evolutionary Architectures (2017)
+
+## Core Idea
+
+Neal Ford, Rebecca Parsons, and Patrick Kua coined "evolutionary architecture": architecture that supports guided, incremental change across multiple dimensions. Requirements, data, and constraints will shift — the question is whether the architecture absorbs that change gracefully or resists it catastrophically. Foundational modularity work by David Parnas argues that the effectiveness of modularization depends on the criteria used to divide the system, tying it directly to flexibility and comprehensibility. Evolvability is a first-class architectural quality attribute, not an afterthought. Martin Fowler wrote the foreword to the evolutionary architecture book, calling continuous delivery "a crucial enabling factor."
+
+## Violation Patterns
+
+### 1. Big-Bang Rewrite Dependency
+
+**Heuristic:** The system has accumulated so much coupling and rigidity that any significant change requires a massive coordinated effort or complete rewrite.
+
+**Look for:**
+- Feature lead time growing rapidly as the system evolves
+- Small changes have unexpectedly large blast radius
+- "We can't change X without rewriting Y" is common
+- eBay's multi-year migrations from Perl to C++ to Java illustrate the extreme cost
+
+**Refactoring/Remedy:** Apply the Strangler Fig pattern (Fowler, 2004): identify thin slices, introduce a routing facade, coexist with legacy, eliminate old functionality incrementally. Never attempt big-bang rewrites.
+
+### 2. Breaking API Changes Without Versioning
+
+**Heuristic:** API changes deployed without versioning cause cascading client failures.
+
+**Look for:**
+- No version histories on APIs
+- Field removals or renames without deprecation paths
+- Clients that must update synchronously
+- No backward-compatibility tests
+- Azure's versioning policy: "an API version completely defines behaviour — behaviour change requires a version change"
+
+**Refactoring/Remedy:** Adopt API versioning (URI path, header, or query parameter). Enforce backward compatibility as the default — additive changes should never require a version bump. Use expand-and-contract for schema migrations.
+
+### 3. Tight Infrastructure/Persistence Coupling
+
+**Heuristic:** Business logic entangled with specific database technology, ORM frameworks, or cloud SDKs, so migrating storage requires rewriting domain logic.
+
+**Look for:**
+- Domain types depending directly on persistence or transport types (ORM entities, API DTOs)
+- Domain objects requiring framework initialization to instantiate
+- Direct database SDK imports in business logic
+- Technology lock-in visible in the core domain layer
+
+**Refactoring/Remedy:** Clean/onion architecture: domain model is persistence-ignorant. Create adapter/mapper layers. The domain defines what it needs; infrastructure adapts to it. Prefer libraries over frameworks (frameworks are harder to replace).
+
+### 4. Absence of Architectural Fitness Functions
+
+**Heuristic:** No automated mechanisms to detect when architectural qualities (coupling, performance, security) silently degrade over time.
+
+**Look for:**
+- Architecture rules exist only in documentation/wikis
+- No automated dependency checks in CI
+- Coupling metrics not tracked
+- Silent boundary erosion over months
+- Ford et al. define fitness functions as "objective integrity assessments of architectural characteristics"
+
+**Refactoring/Remedy:** Implement fitness functions: automated tests running in CI/CD that enforce architectural constraints. Track DORA metrics (deployment frequency, lead time, change failure rate, MTTR). Use ArchUnit/NetArchTest to enforce dependency rules.
+
+### 5. No Incremental Delivery Capability
+
+**Heuristic:** All changes deployed "big bang" without feature flags, gradual rollout, or rollback capability. Deployment equals release.
+
+**Look for:**
+- No feature flag infrastructure
+- No canary or blue-green deployment capability
+- Changes cannot be rolled back without redeployment
+- Feature branches living longer than one week (indicating inability to do trunk-based development)
+
+**Refactoring/Remedy:** Feature flags decouple deployment from release, enabling instant rollback. Expand-and-contract database migrations prevent destructive schema changes. Invest in CI/CD, automated testing, and trunk-based development.
+
+## System-Scale Notes
+
+- Fitness functions can be categorized: triggered vs. continual, atomic vs. holistic, static vs. dynamic, automated vs. manual.
+- The four DORA metrics directly measure an architecture's capacity for change.
+- Build anticorruption layers to shield your domain from external system changes.
+- Fowler's MonolithFirst: start with a modular monolith, split when proven domain boundaries, operational maturity, and team size justify it.
+- ADRs (Architecture Decision Records) force discipline by requiring teams to articulate why a complex pattern is needed now.
+- Key distinction: YAGNI applies to speculative features, NOT to practices that make software easier to modify. Refactoring, self-testing code, CI/CD, and clean architecture are enabling practices, never YAGNI violations.
+
+## False Positives to Avoid
+
+- Choosing a specific technology (e.g., PostgreSQL) is not an evolvability violation as long as the domain code doesn't depend directly on it. Technology choices are fine; tight coupling to them is the problem.
+- A system without API versioning in internal-only APIs where a single team owns all consumers may be fine — versioning is most critical at organizational or external boundaries.
+- Not every piece of code needs to be behind a feature flag. Feature flags add complexity and are most valuable for high-risk or high-impact changes.
+- A well-designed monolith can be more evolvable than poorly-designed microservices.
diff --git a/prompts/skills/beyond-solid-principles/references/kiss.md b/prompts/skills/beyond-solid-principles/references/kiss.md
new file mode 100644
index 0000000..9abcfc1
--- /dev/null
+++ b/prompts/skills/beyond-solid-principles/references/kiss.md
@@ -0,0 +1,88 @@
+# KISS — Keep It Simple, Stupid
+
+> "Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it." — Brian Kernighan
+
+## Core Idea
+
+Kelly Johnson, lead engineer at Lockheed Skunk Works, coined the principle: design systems so they can be maintained by an average person under pressure. In software, Fred Brooks's 1986 distinction between essential complexity (inherent to the problem) and accidental complexity (introduced by our tools and choices) provides the intellectual framework.
+
+KISS is not "make everything trivial" — it's a bias toward the simplest architecture that satisfies requirements while remaining maintainable and testable. Joel Spolsky coined the "Architecture Astronaut" in 2001: smart thinkers who "go too far up, abstraction-wise" and create "absurd, all-encompassing, high-level pictures of the universe that don't actually mean anything at all." An ICSE 2021 study found that 82% of software professionals believed using trending technologies makes them more attractive to employers — resume-driven development systematically biases teams toward over-engineered solutions.
+
+## Violation Patterns
+
+### 1. Premature Microservices / Over-Distribution
+
+**Heuristic:** Splitting a small product into dozens of services without demonstrated need for independent scaling or deployment. Heavy Kubernetes, service mesh, and complex orchestration for a simple CRUD app.
+
+**Look for:**
+- More services than engineers (Segment's 140 services for 3 engineers)
+- Teams spending more time on infrastructure than features
+- High ratio of infrastructure PRs to feature PRs
+- Azure warns: "microservices require a fundamental shift in mindset" and "overly granular services increase complexity"
+
+**Refactoring/Remedy:** Fowler's MonolithFirst: "Almost all the successful microservice stories have started with a monolith that got too big and was broken up." Start with a modular monolith. Split only when proven domain boundaries, operational maturity, and team size justify it.
+
+### 2. Architecture Astronautics / Over-Abstraction
+
+**Heuristic:** Excessive architectural layers, patterns stacked on patterns, generalized frameworks that few people understand.
+
+**Look for:**
+- 10+ architectural layers
+- CQRS + Event Sourcing + DDD + microservices for a CRUD app
+- A real project where implementing a simple "copy user" feature took two full days instead of hours because of all the layers
+- Generic in-house "frameworks" that no one can explain
+
+**Refactoring/Remedy:** Kent Beck's four rules of Simple Design: passes all tests, reveals intention, has no duplication, has fewest elements. Remove layers that don't deliver proportional value. Treat complexity as a finite budget.
+
+### 3. Resume-Driven Development
+
+**Heuristic:** Technology choices driven by what looks good on resumes rather than what solves the problem. Kafka when REST suffices. Kubernetes for single-team applications.
+
+**Look for:**
+- Technologies whose capabilities far exceed actual usage
+- Significant learning curves imposed on the team for marginal benefit
+- "We chose this because it's popular" rather than "we chose this because we need X"
+- Polyglot persistence without a clear reason
+
+**Refactoring/Remedy:** Jeff Bezos's "one-way door vs. two-way door" framework: reserve heavy analysis for irreversible decisions, use simple reversible solutions elsewhere. Right-size technology to the problem. Pick boring technology where possible.
+
+### 4. Speculative Generality
+
+**Heuristic:** Interfaces with only one implementation, abstract classes never extended, design patterns used "in case we need it later," plugin architectures with one plugin.
+
+**Look for:**
+- Disproportionate complexity for the actual requirements
+- Unused extension points
+- Under-utilized infrastructure capabilities
+- Significant portions of system complexity corresponding to features not used or not on the near-term roadmap
+
+**Refactoring/Remedy:** Remove unused abstractions. Apply YAGNI rigorously. If there's only one implementation, you don't need the interface yet. Add abstraction when the second use case arrives and you understand the axis of variation.
+
+### 5. Excessive Middle Tiers and Indirection
+
+**Heuristic:** Intermediate layers that add latency and complexity without delivering meaningful value — the middle tier that performs only basic CRUD passthrough.
+
+**Look for:**
+- Azure flags "the middle tier that performs only basic CRUD as adding latency/complexity without value"
+- Proxy services that add no logic
+- "Onion architecture" where every layer is a 1:1 passthrough to the next
+- Charity Majors's test: "How long to ship a one-character fix?"
+
+**Refactoring/Remedy:** Remove passthrough layers. If a layer doesn't transform, validate, or make decisions, it's accidental complexity. Measure deployment time for trivial changes as a complexity gauge.
+
+## System-Scale Notes
+
+- The practical measure of KISS violations: disproportionate complexity relative to requirements
+- A declining deployment frequency often signals that architecture has become too complex to change safely
+- A high ratio of infrastructure code to business logic suggests accidental complexity is dominating
+- If onboarding a new engineer takes weeks for what should be a simple domain, the system is over-engineered
+- Fowler: "Don't even consider microservices unless you have a system that's too complex to manage as a monolith"
+- Standardize cross-cutting concerns (logging, monitoring, deployment) to avoid a "complexity tax" multiplying across components
+- Prefer simpler architecture styles when they meet requirements. Treat distribution as an operational trade-off, not a default
+
+## False Positives to Avoid
+
+- A system that has grown legitimately complex because the domain is complex is not violating KISS — KISS targets accidental complexity, not essential complexity
+- Well-established patterns (e.g., MVC, repository pattern, dependency injection) that are idiomatic to the tech stack are not over-engineering — they are conventions that reduce cognitive load
+- A large system with many modules is not inherently complex if each module is simple and boundaries are clear
+- Investment in CI/CD, automated testing, and observability is not over-engineering — these are enabling infrastructure that makes simplicity sustainable
diff --git a/prompts/skills/beyond-solid-principles/references/pola.md b/prompts/skills/beyond-solid-principles/references/pola.md
new file mode 100644
index 0000000..03de48c
--- /dev/null
+++ b/prompts/skills/beyond-solid-principles/references/pola.md
@@ -0,0 +1,95 @@
+# Principle of Least Surprise (POLA)
+
+> "A component of a system should behave in a way that most users will expect it to behave." — PL/I Bulletin, 1967
+
+## Core Idea
+
+Also known as the Principle of Least Astonishment, POLA centers on predictability. The "user" can be an end-user, a fellow programmer, or a future maintainer. Joshua Bloch applied it extensively in *Effective Java* and his influential talk "How to Design a Good API & Why it Matters."
+
+At architecture scale, POLA violations are especially costly because they amplify across distributed boundaries and affect multiple teams. A team migrating a 180k-line Rails monolith suffered 30% data loss in production because `record.metadata = filtered_array` on an ActiveRecord CollectionProxy silently performed a database DELETE — four experienced developers missed it because no one expected an assignment operator to have destructive side effects.
+
+Surprising behavior increases bugs, onboarding cost, and misuse. DevIQ connects POLA to code structure, API design, and error handling: make systems predictable to reduce cognitive load and prevent costly integration errors.
+
+## Violation Patterns
+
+### 1. Inconsistent API Semantics
+
+**Heuristic:** APIs whose HTTP semantics are inconsistent or violate protocol expectations.
+
+**Look for:**
+- GET endpoints that perform destructive actions or modify state
+- HTTP 200 returned on errors with `{"error": "Not found"}` in the body
+- REST APIs using POST for everything instead of appropriate HTTP verbs
+- JavaScript's `fetch()` resolving successfully on 404/500 (common source of bugs)
+- Different status code conventions across endpoints in the same API
+
+**Refactoring/Remedy:** Follow HTTP semantics correctly and consistently. Use 200 for retrieval, 201 Created for POST with Location header, 204 No Content for DELETE, 400/422 for validation errors. Adopt Microsoft REST API Guidelines, Google API Design Guide, or JSON:API specification and enforce uniformly across all service boundaries.
+
+### 2. Naming and Convention Inconsistencies
+
+**Heuristic:** Different naming conventions, patterns, or response formats across the same system.
+
+**Look for:**
+- camelCase in some endpoints, snake_case in others
+- Different pagination patterns across the same API surface
+- Inconsistent error response structures
+- CreateUser, AddCustomer, RegisterAccount that all do slightly different things
+- Different authentication mechanisms for different services
+
+**Refactoring/Remedy:** Adopt and enforce a single style guide across all services. Standardize error response format with consistent fields. Use API linting tools (Spectral, Vacuum) to enforce naming conventions automatically in CI/CD pipelines.
+
+### 3. Silent Side Effects and Destructive Operations
+
+**Heuristic:** Operations that appear innocuous but trigger expensive or destructive side effects.
+
+**Look for:**
+- Assignment operators that delete data (the Rails CollectionProxy example)
+- Methods that modify state despite having query-like names
+- "Simple" reads that cause writes
+- APIs that trigger cascading background jobs undocumented by callers
+- Operations that do more than their name suggests
+
+**Refactoring/Remedy:** Apply Command-Query Separation: methods either return a result or modify state, never both. Method names must accurately describe ALL behavior including side effects. If a method does more than its name suggests, rename or split it. Document side effects prominently.
+
+### 4. Silent Breaking Changes
+
+**Heuristic:** Behavior changes without a contract signal, causing client failures that are hard to diagnose.
+
+**Look for:**
+- API field removals or renames without deprecation warnings
+- Recurrent integration bugs at boundaries after "minor" updates
+- Same user intent behaving differently depending on which service path is hit
+- No versioning strategy
+- Schema modifications that silently break downstream clients
+
+**Refactoring/Remedy:** Treat API versions as behavioral contracts. Additive changes (new fields with defaults) are safe; removals and renames are breaking and require version bumps. Use consumer-driven contract testing (Pact) to catch behavioral deviations before they reach production.
+
+### 5. Tribal Knowledge Requirements
+
+**Heuristic:** Using the system correctly requires undocumented knowledge only learned from experienced team members.
+
+**Look for:**
+- High levels of tribal knowledge required to use an API correctly
+- Developers needing to learn undocumented quirks
+- Surprising performance characteristics (a "list" endpoint that takes 30 seconds)
+- Non-obvious preconditions or operation ordering requirements
+- Log analysis showing spikes in client retries or 4xx errors from competent consumers
+
+**Refactoring/Remedy:** Publish API specs (OpenAPI, AsyncAPI) and keep them current. Describe side effects, idempotency, and performance expectations explicitly. Perform DX reviews — treat internal developers as users of your APIs. Use convention over configuration to provide sensible defaults.
+
+## System-Scale Notes
+
+- Microsoft uses an "Azure REST API Stewardship Board" — dedicated architects who review API designs for consistency before implementation
+- Consumer-driven testing (Pact) reveals surprising behavior from the consumer's perspective and prevents integration failures
+- Developer experience (DX) testing: observe new developers' first attempts to use an API and track where they make incorrect assumptions
+- Log analysis reveals POLA violations: spikes in client retries, clients calling endpoints in wrong order, unusual 4xx frequencies from competent consumers
+- Convention over configuration (Rails, Spring Boot) reduces surprise by providing sensible defaults matching common use cases
+- POLA and KISS reinforce each other: surprising complexity is often a symptom of unnecessary complexity
+- At architecture level, inconsistent behavior across services for the "same" concept often stems from under-DRY patterns
+
+## False Positives to Avoid
+
+- A deliberately different API style for a different audience (e.g., public API vs. internal admin API) is not a POLA violation as long as each is internally consistent
+- Documented breaking changes with proper versioning and migration guides are not violations — the surprise is managed and communicated
+- Performance characteristics that are inherent to the operation (e.g., a report generation endpoint that takes time) are not POLA violations if documented
+- An API that follows its platform's conventions even when those conventions seem odd is usually better than an API that breaks platform conventions to be "more intuitive"
diff --git a/prompts/skills/beyond-solid-principles/references/resilience.md b/prompts/skills/beyond-solid-principles/references/resilience.md
new file mode 100644
index 0000000..0e30a14
--- /dev/null
+++ b/prompts/skills/beyond-solid-principles/references/resilience.md
@@ -0,0 +1,103 @@
+# Design for Failure / Resilience
+
+> "Integration points are the number-one killer of systems." — Michael Nygard, Release It!
+
+## Core Idea
+
+Michael Nygard's foundational truth: every integration point — network call, database query, external API — is a potential failure vector. The principle assumes networks, services, and hardware will fail and engineers must design retries, timeouts, circuit breakers, and fallbacks from the start. Modern architecture guidance treats partial failure as normal, especially in cloud and distributed systems.
+
+Netflix's multi-region failover kept them running during the 2017 AWS S3 outage that cost S&P 500 companies $150 million. Knight Capital lost $460 million in 45 minutes because they had no circuit breaker to halt runaway trades, no real-time anomaly detection, and no safe rollback mechanism. Resilience is not optional for any system that integrates with external dependencies.
+
+## Violation Patterns
+
+### 1. Missing Timeouts
+
+**Heuristic:** Network calls block indefinitely or for excessive duration. Downstream services becoming slow causes upstream thread pools to fill and the caller itself to become unresponsive — classic cascading failure.
+
+**Look for:**
+- HTTP/DB clients with no explicit timeout configuration
+- Default timeouts set to minutes or infinity
+- Blocking calls without async alternatives
+- Thread pool exhaustion under load
+- Azure warns about choosing "a shorter timeout so operations fail fast when likely to fail"
+
+**Refactoring/Remedy:** Configure explicit timeouts on every network call. Non-negotiable. Choose timeouts shorter than the caller's own SLA. Prefer "fail fast" when a required dependency is known to be unavailable.
+
+### 2. Unbounded Retries / Retry Storms
+
+**Heuristic:** Retries without limits or backoff create thundering herd problems. Multiple layers retrying the same request multiply attempts exponentially.
+
+**Look for:**
+- Retry loops without max-attempt limits
+- Retries without exponential backoff and jitter
+- Multiple layers (client → gateway → service → DB) each retrying independently, multiplying load as a product of attempts at each layer
+- Non-idempotent operations retried (causing duplicate side effects)
+- Azure warns: "non-idempotent operations can cause unintended side effects when retried"
+
+**Refactoring/Remedy:** Bounded retries with exponential backoff and jitter. Per-request retry limits. Retry budgets (server-wide or per-client) to contain aggregate retry load. Ensure retried operations are idempotent. Never retry at multiple layers without coordination.
+
+### 3. No Circuit Breakers
+
+**Heuristic:** Clients keep attempting operations against a failing service, wasting resources and potentially preventing downstream recovery.
+
+**Look for:**
+- No circuit breaker pattern (Closed → Open → Half-Open) around external calls
+- P95/P99 latency spikes when a downstream service degrades
+- No fallback behavior when a dependency is down
+- Callers that block and wait rather than fail fast when a service is known to be unavailable
+
+**Refactoring/Remedy:** Implement circuit breakers (Resilience4j, Polly, Hystrix). When the circuit opens, serve cached data, defaults, or reduced functionality (graceful degradation). Azure explicitly differentiates retry (expects eventual success) from circuit breaker (prevents likely-to-fail operations) — combine if retry respects circuit-breaker signals.
+
+### 4. No Bulkhead Isolation
+
+**Heuristic:** One overloaded or slow dependency exhausts shared resources (thread pools, connection pools) and takes down unrelated functions.
+
+**Look for:**
+- Shared thread pools or connection pools across unrelated dependencies
+- One slow service causing all services to degrade
+- No resource partitioning per dependency or per tenant
+- No load shedding under pressure
+
+**Refactoring/Remedy:** Bulkhead pattern: partition resources into separate pools per dependency so one failure domain can only exhaust its own allocation. Combine with throttling and queue-based load leveling. Azure recommends combining bulkheads with retry/circuit breaker/throttling.
+
+### 5. Single Points of Failure / SLA Inversion
+
+**Heuristic:** The system's promised availability depends on a less-reliable downstream service without mitigation. Or: a single instance of a critical component with no redundancy.
+
+**Look for:**
+- Composite SLA math not done (if A is 99.9% and B is 99.9% and C is 99.9%, composite availability drops to 99.7%)
+- One database instance, one message broker, or one service instance with no replicas
+- No health checks or readiness probes
+- Session state stored on individual nodes making recovery impossible
+
+**Refactoring/Remedy:** Redundancy at every critical layer. Multi-instance services with load balancers. Replicated databases. Multi-zone or multi-region for critical paths. Health checks and liveness/readiness probes. Calculate composite SLAs and mitigate where they don't meet requirements.
+
+### 6. No Observability for Failure Detection
+
+**Heuristic:** Failures are invisible until they cascade into full outages. Knight Capital received 97 automated error emails that went unnoticed.
+
+**Look for:**
+- No monitoring of P95/P99 latency per dependency
+- No circuit breaker state transition monitoring
+- No distributed tracing
+- No alerting on error rate spikes
+- Incomplete dashboards for latency, error rates, and resource saturation
+
+**Refactoring/Remedy:** Implement observability through metrics, logs, and distributed traces (OpenTelemetry). Monitor circuit breaker state, retry rates, thread pool utilization, and connection pool usage. Alert on anomalies before they become cascading failures.
+
+## System-Scale Notes
+
+- Nygard's stability patterns: Timeouts, Circuit Breakers, Bulkheads, Retry with Backoff, Graceful Degradation, Fail Fast
+- Netflix's Simian Army: Chaos Monkey (kills instances), Chaos Gorilla (kills AZs), Chaos Kong (kills regions)
+- Cascading failure pattern: latency increases → timeouts → retries → load increases → more latency → collapse. Adding capacity often fails because new instances get saturated immediately
+- Feature flags enable instant rollback without redeployment — the lesson Knight Capital teaches most painfully
+- Asynchronous communication via message queues absorbs failures better than synchronous call chains
+- SRE guidance: define time budgets (deadlines), not just timeouts. Misaligned timeouts can trigger immediate subsequent attempts
+- Google's SRE: "overload and resource exhaustion interactions" are the primary drivers of cascading failures
+
+## False Positives to Avoid
+
+- A system that calls only a single, highly reliable internal dependency (e.g., a co-located database) may not need a full circuit breaker — a timeout and retry with backoff may suffice. Calibrate to risk.
+- Not every service needs multi-region failover. Reserve heavy resilience for critical paths and services with strict SLA requirements.
+- A batch processing system that can tolerate delays may not need circuit breakers — it may be acceptable to retry with longer intervals.
+- Chaos engineering is not required for every project. It is most valuable for systems with complex dependency graphs and strict availability requirements.
diff --git a/prompts/skills/beyond-solid-principles/references/soc.md b/prompts/skills/beyond-solid-principles/references/soc.md
new file mode 100644
index 0000000..5ddb4f6
--- /dev/null
+++ b/prompts/skills/beyond-solid-principles/references/soc.md
@@ -0,0 +1,89 @@
+# Separation of Concerns (SoC)
+
+> "Separation of concerns is the only available technique for effective ordering of one's thoughts." — Edsger Dijkstra, 1974
+
+## Core Idea
+
+Separation of Concerns splits a system into distinct sections — UI, business logic, persistence, infrastructure — so modifying one area does not force changes in others. At the architecture level, it means enforcing clear boundaries between presentation, domain/business rules, persistence/infrastructure, and cross-cutting concerns. Each layer or module should have a well-defined scope and minimal coupling to others.
+
+Microsoft's architecture guidance is direct: "business rules and logic should reside in a separate project, which should not depend on other projects in the application." This enforces the dependency rule from Clean Architecture: source code dependencies point only inward toward higher-level policies. When concerns are properly separated, changing a database technology, UI framework, or messaging system becomes a localized task rather than a system-wide refactor.
+
+## Violation Patterns
+
+### 1. Big Ball of Mud / Boundary Erosion
+
+**Heuristic:** No clear separation between presentation, application, domain, and infrastructure layers. Controllers talk directly to databases and external APIs while containing domain logic.
+
+**Look for:**
+- JSP/Razor pages with embedded SQL queries alongside HTML rendering
+- Active Record objects coupling domain logic tightly to persistence mechanisms
+- UI components that reference specific database tables or message queue names
+- Domain services that inspect HTTP headers or depend on serialization formats
+
+**Refactoring/Remedy:**
+Use layered or hexagonal/clean architecture. Establish explicit project/package structure separating presentation, application, domain, and infrastructure. Enforce dependencies pointing strictly inward. Use architecture test tools (ArchUnit, NetArchTest) to validate that higher layers never reference lower ones.
+
+### 2. Persistence-Driven Design
+
+**Heuristic:** Database schema or ORM model becomes the de facto architecture; business logic lives in stored procedures or is tightly coupled to table structure.
+
+**Look for:**
+- Domain objects requiring specific ORM base classes, parameterless constructors, or persistence-specific attributes
+- Direct database access from multiple unrelated components scattered through the codebase
+- Database schema treated as the integration contract between services
+- Business logic encoded in database views or stored procedures rather than application code
+
+**Refactoring/Remedy:**
+Keep domain models persistence-ignorant. Use repository abstractions and mappers to decouple domain objects from database representation. Prefer programmatic service interfaces over shared persistence as integration points. Treat the database as an infrastructure detail, not an architectural centerpiece.
+
+### 3. UI-Driven Domain Logic
+
+**Heuristic:** Domain logic is duplicated across UI channels (web, mobile, batch) rather than being centralized in a domain or application layer.
+
+**Look for:**
+- Business validation rules implemented separately in frontend code for each delivery channel
+- Presentation layers directly querying data tiers, bypassing application services
+- Documented layer boundaries that exist "on paper" but are routinely bypassed in actual code
+- Different business rule implementations across web and mobile frontends
+
+**Refactoring/Remedy:**
+Centralize domain logic in application or domain services. Enforce that all UI channels call only application-layer services. Treat the UI as a thin presentation layer that orchestrates domain operations, never as a container for business rules.
+
+### 4. Cross-Cutting Concern Leakage
+
+**Heuristic:** Logging, caching, authorization, and retry logic are spread arbitrarily through all layers rather than being centralized or coordinated.
+
+**Look for:**
+- Copy-pasted logging, retry, and security check code across multiple modules
+- No middleware, filter, decorator, or AOP patterns despite multiple places needing the same cross-cutting logic
+- Each module independently implementing its own version of authentication, rate-limiting, or monitoring
+
+**Refactoring/Remedy:**
+Use middleware, filters, decorators, or Aspect-Oriented Programming for cross-cutting concerns. Encapsulate shared infrastructure logic in reusable components. This centralizes concern management and makes policy changes easier.
+
+### 5. Technical-Layer Decomposition in Distributed Systems
+
+**Heuristic:** Microservices are organized by technical concern ("Controller Service", "Repository Service", "Notification Service") rather than business capability.
+
+**Look for:**
+- Services that slice horizontally by technical function instead of vertical business domains
+- Feature changes that require coordinated edits across many services and their databases
+- Architecture discussions framed in technology terms rather than business capability terms
+- Services that are tightly coupled because they share infrastructure responsibility
+
+**Refactoring/Remedy:**
+Organize services around business capabilities and bounded contexts. Each service should own its domain slice end-to-end, including presentation, application logic, and persistence for that capability.
+
+## System-Scale Notes
+
+- **Monolith:** Enforce SoC via project/assembly/package structure. Use architecture test tools (ArchUnit, NetArchTest) to assert rules like "no UI class references infrastructure directly."
+- **Microservices:** Services should be designed around business capabilities, not horizontal layers. Avoid shared databases as integration contracts; each service owns its data.
+- **Detection:** Use Robert C. Martin's coupling metrics (Ca, Ce, instability index). Adam Tornhill's change-coupling analysis reveals hidden violations: files that always change together but reside in different modules signal boundary erosion.
+- **Contract-first design:** Define explicit interfaces between layers and bounded contexts to prevent leaking internal structures.
+
+## False Positives to Avoid
+
+- A facade or orchestration layer that coordinates multiple concerns is not a violation — coordination across concerns is its single, legitimate responsibility.
+- Cross-cutting middleware that touches multiple layers (e.g., request-scoped correlation ID injection) is not a violation; it is infrastructure that serves all layers uniformly.
+- A monolith with modules in the same deployment unit is fine as long as dependency direction is enforced; physical separation into services is not required for SoC.
+- A service that handles multiple related operations within a coherent domain (e.g., an Order service managing creation, updates, and fulfillment) respects SoC because the domain is unified.
diff --git a/prompts/skills/beyond-solid-principles/references/srp-sys.md b/prompts/skills/beyond-solid-principles/references/srp-sys.md
new file mode 100644
index 0000000..953b75c
--- /dev/null
+++ b/prompts/skills/beyond-solid-principles/references/srp-sys.md
@@ -0,0 +1,89 @@
+# Single Responsibility — System Level
+
+> "A module should be responsible to one, and only one, actor." — Robert C. Martin
+
+## Core Idea
+
+At the architecture scale, Single Responsibility Principle means each module, service, or bounded context owns one coherent business capability and has one primary reason to change. Azure's microservices architecture guidance states: "each service implements a single business capability within a bounded context." When this principle reaches its logical endpoint, you get a microservices architecture where each service is independently deployable and owned by a single team.
+
+Even in a monolith, each module should have a crisp, memorable purpose. If you need multiple paragraphs to describe what a module does, you likely need more than one module. The principle applies at multiple scales: functions should have one job, classes should have one reason to change, modules should own one coherent business capability, and services should implement one business domain.
+
+## Violation Patterns
+
+### 1. God Service / Kitchen-Sink Module
+
+**Heuristic:** A service or module responsible for user management, billing, notifications, and reporting all at once. Its API surface and codebase grow without coherent focus.
+
+**Look for:**
+- A single service exposing 10+ unrelated API endpoints spanning multiple business domains
+- Multiple teams or squads coordinating changes to the same service
+- Service backlog mixing unrelated business initiatives from different stakeholders
+- The component is a universal dependency; many unrelated features import from it
+
+**Refactoring/Remedy:**
+Identify "mini domains" or business slices inside the overgrown service. Extract along those seams using the Strangler Fig pattern to gradually migrate functionality. Apply Domain-Driven Design strategic design (bounded context mapping, context mapping) to find natural business boundaries.
+
+### 2. Distributed Monolith / Lock-Step Deployment
+
+**Heuristic:** Multiple services that must be deployed together despite being technically separate components.
+
+**Look for:**
+- Changes to one service routinely require synchronized changes in others
+- Services share databases or database schemas across application boundaries
+- Deploying a single user-profile change requires redeploying 10 unrelated backend services
+- Lock-step deployment is normal practice rather than an exceptional circumstance
+
+**Refactoring/Remedy:**
+Redraw service boundaries so each can be deployed independently. Each service should own its own data store and database schema. Use asynchronous communication (events, queues) to decouple deployments. Validate boundaries by asking: "Can I deploy this service alone without coordinating with others?"
+
+### 3. Bounded Context Drift
+
+**Heuristic:** A context (e.g., "Orders") starts handling inventory, shipping, and payments because it was "convenient", creating unintended coupling across domains.
+
+**Look for:**
+- A module that changes for many unrelated reasons (product pricing logic, regulatory updates, UI redesign, logging policies all modify the same module)
+- High commit activity in a single module spanning multiple distinct business domains
+- Modules with unclear or expansive purpose; descriptions use "and", "or", "also" repeatedly
+
+**Refactoring/Remedy:**
+Perform a "reasons to change" analysis for each module. Document what changes would trigger changes to that module. Align boundaries with business capabilities using DDD strategic design. Involve domain experts to validate that boundaries match business reality.
+
+### 4. Gateway/Orchestrator Accumulating Domain Knowledge
+
+**Heuristic:** API gateways or orchestration layers accumulate domain logic that belongs in the services themselves.
+
+**Look for:**
+- Gateway code containing business validation, transformation logic, or domain-specific routing beyond simple proxying
+- The gateway becomes a coupling bottleneck that must change whenever any downstream service changes
+- Business rules encoded in gateway configuration or routing logic rather than in service code
+
+**Refactoring/Remedy:**
+Keep domain knowledge out of the gateway. Push domain logic into the services that own the bounded context. The gateway should handle only cross-cutting concerns like authentication, rate-limiting, and protocol translation. Maintain a clean separation between infrastructure orchestration and domain logic.
+
+### 5. Chatty Service Communication
+
+**Heuristic:** Two services require excessive synchronous communication to implement a single user-visible capability.
+
+**Look for:**
+- Distributed traces showing 5+ synchronous calls between two services for one user action
+- High inter-service call volume for what should be simple operations
+- Services that are effectively parts of the same responsibility split too early
+- Average latency increases significantly because of sequential inter-service calls
+
+**Refactoring/Remedy:**
+If two services are chatty, their functionality may belong in the same service. Azure's guidance: "chatty calls are a symptom that functions might belong in the same service." Prefer starting with coarser-grained services; splitting a service is easier than merging functionality across multiple services. Use asynchronous events or sagas for truly distributed operations.
+
+## System-Scale Notes
+
+- **Monolith:** SRP applies to modules and packages as much as to services. A monolith with no internal boundaries (one massive project with 50 unrelated responsibilities) violates SRP even without any service decomposition.
+- **Microservices:** Azure advises starting coarse-grained when uncertain about boundaries. "Splitting one service into two is easier than refactoring functionality across several existing services." Over-splitting early is more expensive than merging later.
+- **Conway's Law:** Pair organizational team structures to bounded contexts so organizational boundaries reinforce and clarify architectural ones.
+- **Discovery techniques:** Event Storming (Alberto Brandolini) and Context Mapping (Eric Evans) help identify whether boundaries are correctly drawn before problems emerge in production.
+- **Validation metrics:** Use "independent deployability" and "no chatty calls" as first-class constraints when validating whether service boundaries are appropriate.
+
+## False Positives to Avoid
+
+- A service that handles multiple operations within a single coherent business domain is fine (e.g., an Order service managing order creation, updates, status transitions, and cancellation — all part of unified order management).
+- A monolith module with many classes but a single, clear business focus does not violate SRP. The principle is about coherent responsibility, not code size.
+- An orchestrator or saga that coordinates a multi-step business process across multiple services has coordination as its responsibility — that is its single, legitimate purpose and not a violation.
+- A utility or infrastructure library that multiple services depend on is not a god service; it has a clear, focused infrastructure responsibility.
diff --git a/prompts/skills/beyond-solid-principles/references/yagni.md b/prompts/skills/beyond-solid-principles/references/yagni.md
new file mode 100644
index 0000000..d5fc028
--- /dev/null
+++ b/prompts/skills/beyond-solid-principles/references/yagni.md
@@ -0,0 +1,93 @@
+# YAGNI — "You Aren't Gonna Need It" at Architecture Level
+
+> "The most expensive features are the ones you never needed." — Martin Fowler
+
+## Core Idea
+
+Fowler identifies four costs of building presumptive features: the cost of build (wasted effort), the cost of delay (revenue-generating features deferred), the cost of carry (added complexity slowing all subsequent development), and the cost of repair (the feature is often built wrong because understanding evolves).
+
+Research by Kohavi et al. at Stanford and Microsoft found that only one-third of carefully analyzed features actually improved the metrics they were designed to improve — meaning two-thirds of speculative features are wrong. At architecture scale, YAGNI targets premature adoption of complex patterns: full microservices, event sourcing, multi-region active-active, elaborate plugin architectures — when current requirements do not demand them.
+
+The Last Responsible Moment principle from Lean Software Development instructs: delay irreversible decisions until failing to decide would eliminate an important alternative. This is not procrastination — it's disciplined decision-making with the best available information.
+
+## Violation Patterns
+
+### 1. Premature Microservices Decomposition
+
+**Heuristic:** A system decomposed into many microservices without demonstrated need, creating operational overhead that far exceeds business value.
+
+**Look for:**
+- More services than engineers (Segment's canonical case: 140+ microservices for 3 engineers)
+- Consolidation attempts producing massive gains (Segment saw 46 shared library improvements in one year vs. 32 during the entire microservices era)
+- Amazon Prime Video scaling failures (distributed serverless microservices hit 5% of expected throughput, consolidated into one ECS process for 90% cost reduction)
+- Teams spending more time debugging cross-service issues than building features
+
+**Refactoring/Remedy:** Adopt Fowler's MonolithFirst approach. Start with a well-modularized monolith with clear module boundaries. Split only when proven domain boundaries, operational maturity, and team size justify it. "Almost all successful microservice stories have started with a monolith that got too big."
+
+### 2. Speculative Generality / Unused Extension Points
+
+**Heuristic:** Interfaces with single implementations, strategy patterns with one strategy, plugin architectures with one plugin, abstract classes never extended.
+
+**Look for:**
+- Disproportionate ratio of infrastructure PRs to feature PRs
+- Engineers spending more time on infrastructure maintenance than feature development
+- Significant complexity for features not on the near-term roadmap
+- The answer to "What current requirement does this serve?" begins with "What if someday..." rather than "Currently we need..."
+
+**Refactoring/Remedy:** Remove unused abstractions ruthlessly. Apply the Rule of Three — don't abstract until you see three instances. Add generality only when the second or third use case arrives and you understand the axis of variation. Make concrete before making generic.
+
+### 3. Over-Provisioned Infrastructure
+
+**Heuristic:** Many environments, regions, replicas, and complex orchestration for a system that doesn't yet need that scale or availability.
+
+**Look for:**
+- Kubernetes for single-team applications
+- Kafka event systems when REST suffices
+- Multi-region active-active for an internal tool used by 50 people
+- Many environments and replicas sitting unused
+- Complex infrastructure that exists "in case we need to scale"
+
+**Refactoring/Remedy:** Right-size technology to the problem. Use metrics and production data to justify scaling decisions, not speculation. Jeff Bezos calls these "two-way door" decisions — make them quickly and cheaply with simple solutions. Add capacity when data proves necessity, not when fear suggests possibility.
+
+### 4. Premature Pattern Application
+
+**Heuristic:** Advanced architectural patterns (CQRS, Event Sourcing, Saga orchestration, hexagonal architecture) applied everywhere including trivial modules.
+
+**Look for:**
+- CQRS + Event Sourcing for simple CRUD operations
+- Full DDD tactical patterns (Aggregates, Value Objects, Domain Events) in a module with 3 entities
+- Distributed transaction infrastructure with only one database
+- Pattern proliferation that makes simple changes complex
+- Team velocity declining as infrastructure complexity grows
+
+**Refactoring/Remedy:** Apply advanced patterns selectively where justified by complexity or scale. Kent Beck's four rules of Simple Design counter the impulse to add flexibility for speculative needs. Design for replaceability (encapsulate behind interfaces) rather than speculative generality. Add patterns when the pain appears, not before.
+
+### 5. Over-General Domain Models
+
+**Heuristic:** Extremely generic domain models or "frameworks" designed to handle hypothetical future use cases, making concrete features harder to implement.
+
+**Look for:**
+- Domain entities with dozens of optional/nullable fields for "future use"
+- Overly abstract inheritance hierarchies requiring interpretation
+- Configuration-driven behavior harder to understand than code
+- The phrase "we built a platform" when a simple application was needed
+- Configuration complexity exceeding the complexity of the domain itself
+
+**Refactoring/Remedy:** Build specific solutions for known requirements. Harvest patterns after they emerge rather than predicting them. Fowler's Harvested Platform: build well-factored applications, notice duplication between them, then extract shared code. Make the happy path obvious and easy.
+
+## System-Scale Notes
+
+- **CRITICAL DISTINCTION:** YAGNI applies to speculative features, NOT to practices that make software easier to modify. Refactoring, self-testing code, CI/CD, and clean architecture are enabling practices — they are never YAGNI violations
+- The Last Responsible Moment: delay irreversible decisions until failing to decide would eliminate an important alternative. This is not procrastination — it's making decisions with the best available information
+- Architecture Decision Records (ADRs) force discipline by requiring teams to articulate why a complex pattern is needed now
+- Feature flags and toggles help keep partial work from forcing big-bang releases — these are tools for YAGNI compliance
+- Treat "future needs" as hypotheses and validate with production data before paying the full complexity cost
+- Segment's consolidation story: "Instead of enabling us to move faster, the small team found themselves mired in exploding complexity"
+
+## False Positives to Avoid
+
+- Investing in CI/CD, automated testing, observability, and clean code practices is NOT a YAGNI violation — these enable future change and are always justified
+- A well-chosen abstraction boundary that makes testing easier is not speculative generality — testability is a current requirement
+- Security and compliance requirements are not speculative — if regulations require audit logging, encryption, or access controls, implementing them now is not YAGNI
+- Designing for replaceability (e.g., putting a database behind a repository interface) is not YAGNI — it's good architectural hygiene that costs almost nothing upfront
+- Building monitoring, logging, and alerting infrastructure is not speculative — these are operational necessities from day one