docs(skills): add Overview and Red Flags sections (Phase 3)

skills/component-boundary-ownership/SKILL.md

@@ -5,6 +5,12 @@ description: Use when user decides repository organization, where functionality
 
 # Component Boundary Ownership
 
+## Overview
+
+Determine macro-level repository organisation and component boundaries based on deployment
+independence, team ownership, coupling analysis, and reuse patterns. Delegates micro-level
+concerns (intra-component file layout) to scoped-colocation skill.
+
 Ensure clear ownership and minimal coupling when organizing repositories. Determines macro
 placement (which component owns what), delegates micro placement (file layout within
 components) to scoped-colocation.

skills/csharp-best-practices/SKILL.md

@@ -9,6 +9,13 @@ description: >-
 
 # C# Best Practices (Version-Aware Skill)
 
+## Overview
+
+Apply C# best practices appropriate to the project's effective language version. This skill
+detects the language/runtime configuration, prefers the newest supported features, and
+consults version-specific references progressively from C# 10 upward while respecting
+repository conventions.
+
 ## Intent
 
 Apply C# best practices appropriate to the project's **effective language version**.
@@ -141,3 +148,16 @@ If clarification is requested, record:
 - Do not enable preview features unless explicitly configured.
 - Do not upgrade SDK or TFM unless requested.
 - Avoid unrelated formatting changes and "style churn".
+
+## Red Flags - STOP
+
+These statements indicate misalignment with C# best practices:
+
+| Thought                                    | Reality                                                             |
+| ------------------------------------------ | ------------------------------------------------------------------- |
+| "Let's use C# 14 features everywhere"      | Match the project's effective language version; don't assume latest |
+| "Enable all analyzers globally"            | Optional analyzers need clarification; mass changes cause churn     |
+| "Preview features are fine for production" | Avoid preview unless explicitly configured and justified            |
+| "Upgrade the TFM while fixing this bug"    | Don't upgrade SDK/TFM unless explicitly requested                   |
+| "This code style is better"                | Avoid unrelated formatting changes; focus on the task at hand       |
+| "Apply the latest patterns to all code"    | Only modify touched code unless broader refactor is requested       |

skills/dotnet-bespoke-code-minimisation/SKILL.md

@@ -3,6 +3,12 @@ name: dotnet-bespoke-code-minimisation
 description: Bias against bespoke scripts/frameworks by default; prefer mature open-source tools and composable libraries with clear ownership.
 ---
 
+## Overview
+
+Bias against bespoke internal implementations by preferring mature open-source tools and
+composable libraries. When custom code is unavoidable, enforce justification rubrics that
+require explicit rationale, ownership, versioning, testing, and security considerations.
+
 ## Core
 
 ### When to use
@@ -184,3 +190,16 @@ Evidence required in PR:
       zero-dependency model"
 - [ ] Tests: Core mappings covered
 - [ ] Documentation: Mapping conventions explained (if non-obvious)
+
+## Red Flags - STOP
+
+These statements indicate bypass of bespoke minimisation principles:
+
+| Thought                             | Reality                                                         |
+| ----------------------------------- | --------------------------------------------------------------- |
+| "We need full control over this"    | OSS libraries offer customisation; evaluate before rejecting    |
+| "OSS is too heavy for our needs"    | Measure actual overhead; most libraries are well-optimised      |
+| "We're special, our case is unique" | Most "unique" cases have OSS solutions; search thoroughly       |
+| "I can write this in a day"         | Maintenance cost exceeds initial development; OSS shifts burden |
+| "External dependencies are risky"   | Well-maintained OSS with active communities reduces risk        |
+| "We'll document it later"           | Undocumented internal code becomes unmaintainable quickly       |

skills/dotnet-best-practices/SKILL.md

@@ -9,6 +9,13 @@ description: >
 
 # .NET best practices (version-aware, progressive-loading)
 
+## Overview
+
+Apply modern .NET platform capabilities and recommended engineering practices across the full
+lifecycle of a .NET codebase. This skill covers runtime/framework choices, SDK/tooling,
+packaging, deployment strategy, and version-aware best practices for implementation,
+maintenance, and code review scenarios.
+
 ## Purpose
 
 Apply modern .NET platform capabilities and recommended engineering practices across the
@@ -120,3 +127,16 @@ When used during code review, apply this skill to evaluate:
 - Cumulative upgrade checklist when crossing multiple majors.
 - Risks/breaking-change checklist and required test gates (contract/perf/integration).
 - Repository standards updates (packaging, analyzers, SDK pinning, CI enforcement).
+
+## Red Flags - STOP
+
+These statements indicate misalignment with .NET best practices:
+
+| Thought                                     | Reality                                                                   |
+| ------------------------------------------- | ------------------------------------------------------------------------- |
+| "We'll stay on .NET 6 indefinitely"         | LTS versions have end-of-life dates; plan upgrades proactively            |
+| "Sync-over-async is fine for this case"     | Async should be end-to-end; sync-over-async causes thread pool starvation |
+| "We don't need analyzers"                   | Analyzers catch issues at compile time; enable and address warnings       |
+| "NuGet package versions in csproj are fine" | Use Central Package Management for consistency and security               |
+| "Security patches can wait"                 | Runtime security updates need defined SLAs; treat as routine work         |
+| "AOT/trimming will just work"               | Validate compatibility before enabling; many patterns are incompatible    |

skills/dotnet-domain-primitives/SKILL.md

@@ -3,6 +3,13 @@ name: dotnet-domain-primitives
 description: Prevent primitive obsession by enforcing StronglyTypedIds and value objects in domain models and at boundaries.
 ---
 
+## Overview
+
+Prevent primitive obsession by enforcing strongly typed identifiers and value objects in
+domain models. Conversions to/from primitives are permitted only at explicit boundaries
+(persistence, transport, serialization), ensuring type safety and validation throughout
+the domain layer.
+
 ## Core
 
 ### When to use
@@ -194,3 +201,16 @@ public class CustomerMapper
 - New entities/aggregates use typed IDs.
 - No domain-layer primitive IDs added.
 - Boundary conversion is explicit and covered by unit tests.
+
+## Red Flags - STOP
+
+These statements indicate primitive obsession patterns:
+
+| Thought                               | Reality                                                       |
+| ------------------------------------- | ------------------------------------------------------------- |
+| "Guid is fine for identifiers"        | Primitive IDs lose type safety; use strongly typed IDs        |
+| "String is good enough for email"     | Value objects centralise validation; prevent invalid data     |
+| "Implicit conversions are convenient" | Implicit conversions obscure boundaries; be explicit          |
+| "Domain types add too much ceremony"  | Source generators eliminate boilerplate; use them             |
+| "We'll add types later"               | Retrofitting types is expensive; start with them              |
+| "Validation can happen anywhere"      | Centralise validation in domain types; single source of truth |

skills/dotnet-efcore-practices/SKILL.md

@@ -3,6 +3,12 @@ name: dotnet-efcore-practices
 description: Standardise EF Core usage: isolate migrations in a dedicated project excluded from code coverage, and enforce attribute-linked dedicated type configuration classes.
 ---
 
+## Overview
+
+Standardise Entity Framework Core usage with dedicated migrations projects excluded from code
+coverage, attribute-linked configuration types for entities, and deterministic configuration
+discovery. This ensures clean separation between business logic and infrastructure scaffolding.
+
 ## Core
 
 ### When to use
@@ -246,3 +252,16 @@ Expected: File contains exclusion patterns for migrations path (e.g., `**/Migrat
 - [ ] xUnit repository tests use `IAsyncLifetime` for async setup/teardown
 - [ ] Configuration types exist in Persistence project (not in migrations)
 - [ ] Migration files are in dedicated `*.Persistence.Migrations` project only
+
+## Red Flags - STOP
+
+These statements indicate EF Core hygiene issues:
+
+| Thought                                    | Reality                                                            |
+| ------------------------------------------ | ------------------------------------------------------------------ |
+| "Migrations can stay in the main project"  | Isolate migrations in a dedicated project; they're scaffolding     |
+| "OnModelCreating is fine for all config"   | Use dedicated configuration types per entity; keep DbContext clean |
+| "Coverage should include migrations"       | Exclude migrations from coverage; they're generated infrastructure |
+| "Ad-hoc configuration is faster"           | Attribute-linked discovery ensures consistency; prevents drift     |
+| "In-memory database is enough for tests"   | Use TestContainers for realistic persistence testing when needed   |
+| "Reflection scanning order doesn't matter" | Ensure deterministic ordering; non-determinism causes subtle bugs  |

skills/dotnet-healthchecks/SKILL.md

@@ -3,6 +3,12 @@ name: dotnet-healthchecks
 description: Standardise health check implementation using the AspNetCore.Diagnostics.HealthChecks open-source ecosystem.
 ---
 
+## Overview
+
+Standardise health check implementation using the AspNetCore.Diagnostics.HealthChecks (Xabaril)
+open-source ecosystem. Prefer battle-tested packages over bespoke probes for liveness, readiness,
+and dependency health endpoints across databases, caches, message brokers, and external services.
+
 ## Core
 
 ### When to use
@@ -321,3 +327,16 @@ public class HealthCheckWithTestContainersTests : IAsyncLifetime
     }
 }
 ```
+
+## Red Flags - STOP
+
+These statements indicate health check anti-patterns:
+
+| Thought                              | Reality                                                        |
+| ------------------------------------ | -------------------------------------------------------------- |
+| "We'll write our own health checks"  | Use Xabaril packages; they're battle-tested for common deps    |
+| "Liveness should check the database" | Liveness checks process state only; database is for readiness  |
+| "One health endpoint is enough"      | Separate liveness from readiness; prevent unnecessary restarts |
+| "Health checks don't need tests"     | Test both unit (IHealthCheck) and integration (endpoints)      |
+| "Embed connection strings directly"  | Use configuration; avoid secrets in health check registration  |
+| "Any failure should restart the pod" | Readiness failures remove from LB; only liveness restarts      |

skills/dotnet-mapping-standard/SKILL.md

@@ -3,6 +3,12 @@ name: dotnet-mapping-standard
 description: Standardise mapping (DTOs/contracts/persistence models) using source-generated mappers and explicit boundary conversions.
 ---
 
+## Overview
+
+Standardise mapping between DTOs, domain models, and persistence models using source-generated
+mappers. Mappings live at explicit boundaries (API, infrastructure) with deterministic,
+testable conversion paths and no runtime reflection magic.
+
 ## Core
 
 ### When to use
@@ -118,3 +124,16 @@ When reviewing mappers registered in DI:
 - [ ] Is injection for "testability only"?
   - **YES**: Reject - test static mappers directly
   - **NO**: Injection acceptable
+
+## Red Flags - STOP
+
+These statements indicate mapping anti-patterns:
+
+| Thought                                 | Reality                                                         |
+| --------------------------------------- | --------------------------------------------------------------- |
+| "AutoMapper conventions will handle it" | Explicit mapping prevents runtime surprises; be deliberate      |
+| "Mapping logic belongs in the entity"   | Keep entities clean; mappers handle boundary concerns           |
+| "Inject the mapper for testability"     | Pure mappers don't need DI; test static mappers directly        |
+| "Runtime reflection is fine"            | Source-generated mappers are faster and fail at compile time    |
+| "Implicit conversions are convenient"   | Explicit conversions make boundary crossings visible            |
+| "Round-trip tests aren't worth it"      | Round-trip tests catch subtle mapping bugs; always include them |

skills/dotnet-open-source-first-governance/SKILL.md

@@ -3,6 +3,12 @@ name: dotnet-open-source-first-governance
 description: Enforce open-source-first dependency selection with mandatory live license revalidation (web search) and review-time gating.
 ---
 
+## Overview
+
+Enforce open-source-first dependency selection with mandatory live license revalidation at
+review time. Historical OSS status is insufficient; verify current licensing via web search
+for every dependency selection, upgrade, or review to catch recent licensing changes.
+
 ## Core
 
 ### When to use
@@ -71,3 +77,16 @@ When encountering a new library, an upgrade, or a dependency review, the agent m
 1. perform a live web search for current licensing,
 2. flag ambiguity or recent changes,
 3. mark the dependency **unapproved** if licensing cannot be verified confidently.
+
+## Red Flags - STOP
+
+These statements indicate license governance bypass:
+
+| Thought                                | Reality                                               |
+| -------------------------------------- | ----------------------------------------------------- |
+| "It was open source last time"         | Licenses change; revalidate with every upgrade        |
+| "The package name sounds open source"  | Verify the LICENSE file directly; names mislead       |
+| "Transitive deps don't matter"         | Critical transitives need license checks too          |
+| "We'll check licensing before release" | Check at PR time; late discovery is costly            |
+| "Source-available is the same"         | Source-available often has restrictions; verify terms |
+| "Copyleft is fine for internal tools"  | Distribution models matter; understand obligations    |

skills/dotnet-source-generation-first/SKILL.md

@@ -3,6 +3,13 @@ name: dotnet-source-generation-first
 description: Prefer compile-time source generation over runtime evaluation for repetitive cross-cutting concerns (mapping, logging, regex, etc.).
 ---
 
+## Overview
+
+Prefer compile-time source generation over runtime reflection for repetitive cross-cutting
+concerns like mapping, serialization, regex, and logging. Source generation provides
+determinism, compile-time verification, reduced runtime overhead, and better AOT/trimming
+compatibility.
+
 ## Core
 
 ### When to use
@@ -110,3 +117,16 @@ Reflection/runtime codegen may be used when:
   - a justification,
   - a benchmark or measurable rationale,
   - confirmation that no suitable OSS source-gen alternative exists.
+
+## Red Flags - STOP
+
+These statements indicate source generation bypass:
+
+| Thought                            | Reality                                                  |
+| ---------------------------------- | -------------------------------------------------------- |
+| "Reflection is more flexible"      | Source gen handles most cases; flexibility rarely needed |
+| "Startup cost doesn't matter"      | AOT/trimming require source gen; plan for it early       |
+| "We'll optimize later"             | Retrofitting source gen is expensive; start with it      |
+| "No source-gen library exists"     | Check thoroughly; ecosystem is rapidly growing           |
+| "It's just a few operations"       | Hot paths compound; measure before dismissing            |
+| "Dynamic types require reflection" | True for plugins; false for most business code           |

skills/dotnet-specification-pattern/SKILL.md

@@ -3,6 +3,12 @@ name: dotnet-specification-pattern
 description: Prefer Specification Pattern for query composition and domain selection logic; avoid generic Repository Pattern duplication of ORM semantics.
 ---
 
+## Overview
+
+Prefer the Specification Pattern over generic Repository Pattern for query composition and
+domain selection logic. Specifications define what to fetch while infrastructure decides how
+to execute, enabling composable, testable selection logic without exposing ORM details.
+
 ## Core
 
 ### When to use
@@ -164,3 +170,16 @@ var customers = await _repo.ListAsync(
 2. **Week 2**: Extract 3-5 most-used query patterns into specifications
 3. **Week 3**: Deprecate generic query methods (`GetAll()`, `Find()`)
 4. **Week 4**: Remove deprecated methods, enforce specs in code review
+
+## Red Flags - STOP
+
+These statements indicate specification pattern misuse:
+
+| Thought                                      | Reality                                                             |
+| -------------------------------------------- | ------------------------------------------------------------------- |
+| "Generic repository with GetAll() is fine"   | GetAll() duplicates ORM semantics; use specifications               |
+| "IQueryable in handlers is convenient"       | Keep IQueryable in infrastructure; expose specs to application      |
+| "Each query needs its own repository method" | Compose specifications instead; avoid method explosion              |
+| "Specifications add too much overhead"       | Named specs improve testability and reuse; worth the structure      |
+| "LINQ in handlers is more readable"          | Scattered LINQ causes duplication; named specs are self-documenting |
+| "N+1 queries are fine for now"               | Specs should include eager loading strategy; prevent N+1 upfront    |

skills/dotnet-testing-assertions/SKILL.md

@@ -3,6 +3,12 @@ name: dotnet-testing-assertions
 description: Standardise unit/integration test assertions on open-source libraries; prefer AwesomeAssertions over non-open-source alternatives.
 ---
 
+## Overview
+
+Standardise test assertions on open-source libraries, preferring AwesomeAssertions (the
+community fork of FluentAssertions) for fluent, readable assertions with better error
+messages. Enforce OSS license revalidation for all test dependencies.
+
 ## Core
 
 ### When to use
@@ -98,3 +104,16 @@ await action.Should().ThrowAsync<NotFoundException>();
 | `Assert.NotNull(obj)`            | `obj.Should().NotBeNull()`     | Chaining support      |
 | `Assert.Contains(item, list)`    | `list.Should().Contain(item)`  | Better error messages |
 | `Assert.Throws<T>(action)`       | `action.Should().Throw<T>()`   | Message assertions    |
+
+## Red Flags - STOP
+
+These statements indicate assertion anti-patterns:
+
+| Thought                               | Reality                                                      |
+| ------------------------------------- | ------------------------------------------------------------ |
+| "xUnit Assert is good enough"         | Fluent assertions provide better error messages and chaining |
+| "Any assertion library will do"       | Ensure OSS license compliance; verify before adopting        |
+| "Assert exact timestamps"             | Use BeCloseTo for time; exact matches are brittle            |
+| "Assert full object equality"         | Use BeEquivalentTo with exclusions; ignore generated fields  |
+| "Over-specify implementation details" | Assert behaviour and outcomes, not implementation            |
+| "Skip license verification"           | All test dependencies need OSS license revalidation          |