@mrciphersmith/keryx 0.3.3 → 0.3.5

package/src/gdskills/bundled/stacks/csharp-dotnet/governance/scout.json

@@ -0,0 +1,33 @@
+[
+  {
+    "query": "Use when implementing or extending a feature in a C#/.NET service or library -- DI registration and lifetimes, async/await (Task vs ValueTask, avoiding async void), nullable reference type annotations, records vs classes, EF Core query shape, and IDisposable/IAsyncDisposable cleanup.",
+    "decision": "fork",
+    "topMatch": "csharp-dotnet/dotnet-code-review",
+    "recordedAt": "2026-09-25T15:34:51.958Z",
+    "skillName": "dotnet-implementation",
+    "justification": "Top match dotnet-code-review is this same pack's read-only review skill (different intent, action verb, and workflow), not a real implementation-skill duplicate; no existing implement skill covers C#/.NET DI lifetimes, Task/ValueTask, nullable reference types, or EF Core query shape."
+  },
+  {
+    "query": "Use when a C#/.NET test project needs writing, extending, or fixing -- xUnit/NUnit Fact/Theory and InlineData/TestCase tables, async test methods, and disciplined Moq/NSubstitute mocking that stubs external seams (HTTP, repository, clock) rather than internal collaborators.",
+    "decision": "create",
+    "topMatch": "swift-ios/swift-testing",
+    "recordedAt": "2026-09-25T15:33:42.746Z",
+    "skillName": "dotnet-testing"
+  },
+  {
+    "query": "Use when reviewing a C#/.NET change for async and resource-safety risks -- async void outside event handlers, sync-over-async (.Result/.Wait()), swallowed/blanket exception catches, missing IDisposable/IAsyncDisposable cleanup, and nullable-annotation gaps. Read-only, no edits.",
+    "decision": "fork",
+    "topMatch": "ts-js-node/nodejs-code-review",
+    "recordedAt": "2026-09-25T15:34:52.239Z",
+    "skillName": "dotnet-code-review",
+    "justification": "Nearest match ts-js-node/nodejs-code-review (0.24-ish overlap) reviews TypeScript/Node concurrency and idiom, not C#'s async-void/sync-over-async/IDisposable vocabulary; no existing review skill covers .NET-specific async and resource-safety anti-patterns."
+  },
+  {
+    "query": "Use when dotnet build/dotnet test fails, or a NuGet restore is broken -- resolves package/target-framework mismatches, compiler errors, nullable-annotation warnings, analyzer/StyleCop findings, and a failing test, with the smallest root-cause fix rather than a suppression.",
+    "decision": "fork",
+    "topMatch": "kotlin-android/kotlin-android-build-fix",
+    "recordedAt": "2026-09-25T15:34:52.517Z",
+    "skillName": "dotnet-build-fix",
+    "justification": "Nearest match kotlin-android/kotlin-android-build-fix fixes Gradle/AGP/Kotlin compiler errors, not dotnet build/NuGet/target-framework/StyleCop findings; each build-fix skill is scoped to its own toolchain's specific failure surface, sharing only the generic 'root cause not suppression' framing."
+  }
+]

package/src/gdskills/bundled/stacks/csharp-dotnet/pack.json

@@ -0,0 +1,38 @@
+{
+  "id": "csharp-dotnet",
+  "family": "language",
+  "modules": ["csharp-dotnet-rules", "csharp-dotnet-skills"],
+  "detectionMarkers": ["csharp", "dotnet", "c#"],
+  "provenance": { "origin": "authored", "sourceRef": "flow 336, Wave 4 batch 4" },
+  "stability": "experimental",
+  "skills": {
+    "implement": ["dotnet-implementation"],
+    "test": ["dotnet-testing"],
+    "review": ["dotnet-code-review"],
+    "build-fix": ["dotnet-build-fix"],
+    "migrate": []
+  },
+  "agentProfile": {
+    "displayName": "C#/.NET",
+    "auditFocus": [
+      "async void used outside an event handler, swallowing any exception the method throws",
+      "a blocking `.Result`/`.Wait()` call on a Task from synchronous code, risking a sync-over-async deadlock",
+      "a public API returning a nullable-looking reference type with nullable annotations disabled, or an unannotated parameter that is dereferenced without a null check",
+      "IDisposable/IAsyncDisposable fields or locals not wrapped in `using`/`await using`, leaking unmanaged resources or connections",
+      "SQL built by string interpolation/concatenation into SqlCommand.CommandText instead of parameterized queries",
+      "a unit test mocking an internal collaborator (a private helper, a concrete implementation detail) instead of the external seam (HTTP client, repository interface, database)"
+    ],
+    "buildCommands": [
+      "dotnet build",
+      "dotnet test",
+      "dotnet format --verify-no-changes",
+      "dotnet build /p:TreatWarningsAsErrors=true /p:EnforceCodeStyleInBuild=true"
+    ],
+    "fixGuardrails": [
+      "never add `#pragma warning disable` or `[SuppressMessage]` to silence a compiler/analyzer warning without fixing or explaining the underlying issue",
+      "never downgrade or disable nullable reference types (`<Nullable>disable</Nullable>` or a blanket `#nullable disable`) just to make a nullability warning disappear",
+      "never pin or downgrade a NuGet package to route around a real incompatibility without saying so in the report",
+      "fix the smallest root cause; do not refactor unrelated code while resolving a build/test/analyzer failure"
+    ]
+  }
+}

package/src/gdskills/bundled/stacks/csharp-dotnet/rules/coding-style.mdc

@@ -0,0 +1,100 @@
+---
+extends: common
+paths: ["**/*.cs"]
+metadata:
+  origin: authored
+---
+
+# C#/.NET coding style
+
+Narrows `core-common-rules`' stack-agnostic style rules to modern C#
+idiom (new project templates enable nullable reference types by
+default since .NET 6/C# 10 — the language itself still defaults
+annotations/warnings off, so an existing project may need `<Nullable>
+enable</Nullable>` added explicitly; primary constructors and
+collection expressions since C# 12/.NET 8).
+Applies only to `*.cs` files — everything not C#-specific still comes
+from the common rules this file `extends`.
+
+## Naming and structure
+
+- `PascalCase` for types, methods, properties, and public/protected
+  members; `camelCase` for locals and parameters; a private field is
+  `_camelCase` with a leading underscore, not `m_field` or bare
+  `camelCase` that can collide with a parameter name.
+- Interfaces are prefixed `I` (`IOrderRepository`), never suffixed
+  (`OrderRepositoryInterface`).
+- One public type per file, file named after the type
+  (`OrderService.cs` for `class OrderService`), unless the type is a
+  small private nested/support type used only inside its owner.
+- File-scoped namespaces (`namespace Orders;`) instead of a nested
+  block, unless the project's existing files already use block-scoped
+  namespaces — match what is there.
+
+## Records, classes, and immutability
+
+- Prefer a `record`/`record class` for a type whose identity is its
+  value (a DTO, a command, an event, an immutable snapshot) — it gets
+  structural equality and a `with` expression for free. Reach for `class`
+  when the type has identity beyond its data, mutable state that changes
+  over its lifetime, or entity semantics an ORM tracks by reference/key.
+- Use `record struct` for a small, frequently-allocated value type where
+  avoiding heap allocation matters; default to a reference `record`
+  otherwise.
+- Favor `init`-only properties (or a primary constructor) over a
+  public setter on anything that should not change after construction —
+  a mutable public setter on a "value" type invites accidental aliasing
+  bugs.
+
+## Pattern matching and modern idiom
+
+- Prefer pattern matching (`is`, `switch` expressions, property patterns,
+  list patterns) over a chain of `if`/`else if` type checks or casts —
+  `if (shape is Circle { Radius: > 0 } c)` reads its own intent; a cast
+  followed by a separate null/type check does not.
+- Use a primary constructor (`class OrderService(IOrderRepository repo)`)
+  for a type whose constructor only assigns its parameters to fields —
+  it removes the boilerplate field-and-assignment block. Fall back to an
+  explicit constructor body once it needs validation, logic, or more than
+  trivial assignment.
+- Use collection expressions (`int[] xs = [1, 2, 3];`, `List<T> ys = [];`)
+  for new collection-literal code instead of `new[] { ... }`/
+  `new List<T> { ... }`, unless the project's existing style has not
+  adopted them yet — match what is there rather than mixing both styles
+  in one file.
+- Expression-bodied members (`public int Total => Items.Sum(i => i.Price);`)
+  for a single-expression method/property/operator; keep a full block
+  body once the member needs more than one statement or local reasoning
+  step — do not force multi-statement logic into one expression via `;`
+  chaining or nested ternaries.
+
+## Nullable reference types
+
+- New projects have the nullable annotation and warning contexts on by
+  default (`<Nullable>enable</Nullable>` in the project file) — keep it
+  on; do not add `<Nullable>disable</Nullable>` or a blanket
+  `#nullable disable` to make warnings go away.
+- A parameter, property, or return type that can genuinely be absent is
+  annotated `?` (`string? middleName`); a public member with no `?` is a
+  promise to callers that it is never null — do not violate that promise
+  with a hidden `null` return "just this once."
+- Use `ArgumentNullException.ThrowIfNull(value)` at a public API's entry
+  point for a reference-typed parameter that must not be null, instead of
+  a hand-rolled `if (value is null) throw new ArgumentNullException(...)`.
+- Resolve a nullability warning by fixing the actual null path (a real
+  null check, a non-null initializer, restructuring so the compiler can
+  see the invariant) — never with the null-forgiving operator (`value!`)
+  as a substitute for an actual guard, except at a boundary where you can
+  state in a comment exactly why the value is provably non-null there.
+
+## `var` usage
+
+- Use `var` when the right-hand side already makes the type obvious
+  (`var order = new Order();`, `var items = order.Items.ToList();`) or
+  when the concrete type is long/generic and adds no clarity
+  (`var lookup = new Dictionary<string, List<OrderLine>>();`).
+- Use an explicit type when `var` would hide the type at a call site that
+  matters for reading correctness (`var result = Parse(input);` where
+  `Parse`'s return type is not obvious from the name) or when the
+  declared type differs meaningfully from the initializer's runtime type
+  (assigning a derived type but declaring the base).

package/src/gdskills/bundled/stacks/csharp-dotnet/rules/patterns.mdc

@@ -0,0 +1,107 @@
+---
+extends: common
+paths: ["**/*.cs"]
+metadata:
+  origin: authored
+---
+
+# C#/.NET patterns
+
+Narrows `core-common-rules`' stack-agnostic design guidance to
+idiomatic C#/.NET design and its common anti-patterns: async/await,
+dependency injection, LINQ, and disposal. Applies only to `*.cs` files.
+
+## Async/await
+
+- Never use `async void` except for an actual event handler
+  (`private async void Button_Click(object sender, EventArgs e)`) — any
+  exception an `async void` method throws cannot be awaited or caught by
+  its caller and crashes the process instead. Every other async method
+  returns `Task` or `Task<T>`.
+- Return `Task`/`Task<T>` for a method whose async work is on the common,
+  usually-awaited path; return `ValueTask`/`ValueTask<T>` only for a
+  hot-path method that frequently completes synchronously (a cache hit),
+  where avoiding the `Task` allocation is measured to matter — a
+  `ValueTask` must be awaited (or converted) exactly once and never
+  stored, unlike a `Task`.
+- In library code that does not need to resume on a captured context
+  (UI thread, ASP.NET classic `SynchronizationContext`), call
+  `.ConfigureAwait(false)` on an awaited `Task` to avoid an unnecessary
+  context-capture and reduce deadlock risk. Modern ASP.NET Core has no
+  such `SynchronizationContext`, so application-level request-handling
+  code in an ASP.NET Core project does not need it — match what the
+  project's own code already does.
+- Never call `.Result`, `.Wait()`, or `.GetAwaiter().GetResult()` on a
+  `Task` from otherwise-synchronous code to "call an async method
+  synchronously" — this is sync-over-async and can deadlock when the
+  awaited call needs to resume on a context the blocking thread is
+  itself occupying. Make the calling method `async` and `await` instead;
+  if the call truly cannot become async (a legacy synchronous interface
+  boundary), that is a design problem to flag, not to paper over.
+
+## Dependency injection
+
+- Register a service at the narrowest lifetime that is correct:
+  `Singleton` for stateless or thread-safe shared state, `Scoped` for
+  per-request/per-unit-of-work state (a `DbContext`, a request-scoped
+  cache), `Transient` for cheap, stateless, or intentionally
+  non-shared instances. Never inject a `Scoped` service into a
+  `Singleton` by capturing it directly — that captures the first
+  request's instance for the app's lifetime; resolve it per-use via
+  `IServiceScopeFactory`/`IServiceProvider.CreateScope()` instead.
+- Depend on an interface (`IOrderRepository`), not a concrete
+  implementation, at a constructor boundary that DI resolves — this is
+  what makes the type unit-testable without a real database/HTTP call.
+- Prefer constructor injection for required dependencies; reserve
+  property injection for genuinely optional dependencies with a working
+  default, which is uncommon.
+
+## LINQ efficiency
+
+- Materialize a query with `.ToList()`/`.ToArray()` before enumerating it
+  more than once (in a loop that also iterates it, or across a
+  `.Count()` followed by a `foreach`) — an `IEnumerable<T>` built from a
+  `IQueryable<T>`/deferred LINQ chain re-runs the whole query (or, worse,
+  a whole database round trip) on every enumeration unless it is
+  materialized once.
+- Avoid stacking multiple `.Where()`/`.Select()` passes over the same
+  large sequence when one combined pass would do — each pass is a full
+  additional enumeration for an in-memory `IEnumerable<T>`.
+- On an `IQueryable<T>` backed by a database (EF Core), keep filtering
+  (`.Where`) and projection (`.Select`) in the query itself so they
+  translate to SQL, rather than calling `.ToList()` early and then
+  filtering in memory — the latter pulls the whole table across the wire
+  first.
+- Use `.Any()` to check for existence, never `.Count() > 0`, which forces
+  a full count when a short-circuiting existence check would do.
+
+## Disposal patterns
+
+- Any local or field holding an `IDisposable` is wrapped in a `using`
+  statement/declaration (`using var conn = new SqlConnection(...);`) or
+  disposed in a `Dispose()`/`finally` block — never left for the
+  finalizer, which is non-deterministic and, for something like an open
+  connection or file handle, holds the resource far longer than needed.
+- Use `await using` for an `IAsyncDisposable` (most modern EF Core/
+  streaming/channel types expose one) so disposal itself is awaited
+  instead of blocking a thread on synchronous `Dispose()`.
+- A class that owns one or more `IDisposable`/`IAsyncDisposable`
+  fields implements `IDisposable`/`IAsyncDisposable` itself and disposes
+  them in its own `Dispose`/`DisposeAsync`, rather than requiring every
+  caller to know which of its fields need cleanup.
+
+## Anti-patterns to flag
+
+- A "god service"/"utils" static class that accumulates unrelated
+  helper methods instead of being split along what the code actually
+  does — the same smell as a Go "god package," expressed as a static
+  class here.
+- Catching `Exception` broadly and continuing as if nothing happened,
+  instead of catching the specific exception type a call can throw (or
+  letting an unexpected one propagate) — see `rules/security.mdc` and
+  `dotnet-code-review`'s focus list for the review-time version of this
+  check.
+- Exposing a mutable `List<T>`/collection field directly as a public
+  property instead of `IReadOnlyList<T>`/`IReadOnlyCollection<T>` (or a
+  defensive copy), which lets any caller mutate internal state through a
+  reference they were only meant to read.

package/src/gdskills/bundled/stacks/csharp-dotnet/rules/security.mdc

@@ -0,0 +1,86 @@
+---
+extends: common
+paths: ["**/*.cs"]
+metadata:
+  origin: authored
+---
+
+# C#/.NET security
+
+Narrows `core-common-rules`' stack-agnostic security rules to
+C#/.NET-specific, OWASP-relevant risks and the safe framework API to use
+instead. Applies only to `*.cs` files.
+
+## SQL and data access
+
+- Use parameterized queries for any SQL built from user-influenced
+  input: `SqlCommand.Parameters.Add(...)`/`AddWithValue(...)` with `@`
+  placeholders, or an ORM's parameterized query API (EF Core LINQ,
+  Dapper's parameter objects) — never `string.Format`/interpolation/
+  concatenation to build `CommandText` with a value that came from a
+  caller. `$"SELECT * FROM Users WHERE Name = '{name}'"` is a SQL
+  injection sink even when it "looks like" it is just formatting.
+- An ORM's raw-SQL escape hatch (EF Core's `FromSqlRaw`, Dapper's raw
+  string execution) carries the same rule: pass user-influenced values
+  as parameters, never interpolated directly into the raw SQL string.
+  Prefer `FromSqlInterpolated`, which parameterizes `$"..."`
+  interpolation holes automatically, over `FromSqlRaw` when the query
+  needs any caller-supplied value at all.
+
+## Deserialization of untrusted data
+
+- Never use `BinaryFormatter` to deserialize data from any source you do
+  not fully trust (or at all, on a current .NET version) — it is banned
+  by Microsoft for security reasons because a crafted payload can
+  execute arbitrary code during deserialization, and it is obsolete/
+  removed on modern .NET.
+- Deserialize untrusted JSON with `System.Text.Json` using an explicit,
+  known target type — avoid `TypeNameHandling`-style polymorphic
+  deserialization from an untrusted source (whether via
+  `Newtonsoft.Json`'s `TypeNameHandling.Auto`/`All` or a custom
+  `$type`-driven resolver), which lets the payload itself choose what
+  type gets constructed.
+- Validate/allowlist any type passed to `XmlSerializer`/`DataContractSerializer`
+  from untrusted input the same way; do not resolve a type name found
+  inside the untrusted payload without an allowlist.
+
+## Secrets and configuration
+
+- Never hard-code a connection string, API key, or signing secret in
+  source or commit it in `appsettings.json` — use User Secrets
+  (`dotnet user-secrets`) for local development and environment
+  variables, Azure Key Vault, or another secret store the project has
+  already standardized on for anything beyond local dev.
+- A connection string or secret read from `IConfiguration` should come
+  from an environment-specific provider (environment variables, a
+  secret manager), not a value checked into `appsettings.json` or
+  `appsettings.Development.json` that happens to work.
+
+## Path and file handling
+
+- Never build a filesystem path for an untrusted, caller-supplied
+  filename/segment with plain string concatenation and open it directly
+  — validate the resulting path stays under the intended root (e.g.
+  resolve with `Path.GetFullPath` and confirm it starts with the root's
+  full path, or use an allowlist of known filenames) before calling
+  `File.Open`/`File.ReadAllText`/etc.; `Path.Combine` alone does not stop
+  a `..`-containing segment from climbing outside the intended
+  directory.
+
+## Web and transport (ASP.NET Core)
+
+- Never render user-influenced content into an HTML response outside of
+  Razor's default auto-encoding (`Html.Raw`/`@Html.Raw` on
+  caller-supplied content is an XSS vector) — let the framework's
+  default encoding do its job unless the content is provably
+  pre-sanitized.
+- Never disable TLS certificate validation
+  (`ServerCertificateCustomValidationCallback` returning `true`
+  unconditionally, or `HttpClientHandler.ServerCertificateCustomValidationCallback`
+  bypassing validation) outside a short-lived local test, and never ship
+  it that way.
+- Use the framework's built-in antiforgery support
+  (`[ValidateAntiForgeryToken]`/`IAntiforgery`) for any state-changing
+  endpoint reachable from a browser session, and rely on ASP.NET Core
+  Identity/`PasswordHasher<TUser>` (or an equivalent vetted library) for
+  password hashing — never a custom hash/roll-your-own scheme.

package/src/gdskills/bundled/stacks/csharp-dotnet/rules/testing.mdc

@@ -0,0 +1,89 @@
+---
+extends: common
+paths: ["**/*.cs"]
+metadata:
+  origin: authored
+---
+
+# C#/.NET testing
+
+Narrows `core-common-rules`' stack-agnostic testing rules to xUnit/NUnit
+convention and disciplined mocking with Moq/NSubstitute. Applies only to
+`*.cs` files.
+
+## Framework and layout
+
+- Match whichever test framework the project already uses (xUnit or
+  NUnit are both common; do not introduce a second one into a project
+  that has standardized on the other). xUnit: `[Fact]` for a single
+  case, `[Theory]` + `[InlineData(...)]`/`[MemberData(...)]` for
+  parameterized cases. NUnit: `[Test]` and `[TestCase(...)]` play the
+  same roles.
+- Tests live in a mirrored `*.Tests`/`*.Test` project (the standard .NET
+  convention: `Orders/` production code, `Orders.Tests/` its tests), not
+  inside the production project itself.
+- Name a test method for behavior, not implementation:
+  `MethodName_Scenario_ExpectedResult`
+  (`Validate_MissingOrderId_ThrowsArgumentException`) reads as a
+  specification; `Test1`/`ValidateTest` does not.
+
+## Table-driven (`Theory`/`TestCase`) tests
+
+- Use `[Theory]` + `[InlineData(...)]` (xUnit) or `[TestCase(...)]`
+  (NUnit) for a set of cases that exercise the same method with
+  different inputs/expected outputs, instead of copy-pasting a near-
+  identical `[Fact]`/`[Test]` per case — each data row becomes its own
+  reported test result, so a failure names exactly which input failed.
+- Reach for `[MemberData(nameof(Cases))]`/a `TestCaseSource` when a case
+  needs a non-primitive value (an object, a collection) that attribute
+  arguments cannot express directly.
+
+## Async tests
+
+- A test that exercises `async` production code is itself `async Task`
+  (`public async Task Validate_ValidOrder_ReturnsSuccess()`), and awaits
+  the call under test — never `async void` (the test runner cannot await
+  it, and any assertion failure or exception inside it is lost instead
+  of failing the test) and never a blocking `.Result`/`.Wait()` on the
+  Task under test as a substitute for `await`.
+
+## Mocking boundaries: mock the seam, not the internals
+
+- Mock/stub an **external dependency the unit under test talks to
+  through an interface** — an `HttpClient`-backed API client behind an
+  interface, a repository interface wrapping the database, a clock/time
+  provider, a message publisher — using Moq (`Mock<IThing>`) or
+  NSubstitute (`Substitute.For<IThing>()`).
+- Do **not** mock an internal collaborator that is itself part of what
+  the test is supposed to verify — a private helper method, a concrete
+  value object, a piece of the same class's own logic split into another
+  method for readability. Mocking one layer too deep proves only that
+  the mock returns what you told it to, not that the unit under test
+  actually behaves correctly; it also makes the test brittle to harmless
+  internal refactors that change nothing about observable behavior.
+- The question to ask before adding a mock: "does the real system cross
+  a process/network/disk boundary here (HTTP, database, filesystem,
+  clock, random), or am I mocking a class my own code owns and could
+  just construct for real?" Only the former earns a mock.
+- Verify a mock's interaction (`mock.Verify(...)`/
+  `receivedCall.Received()`) only for a call whose occurrence is itself
+  part of the contract being tested (e.g. "an email is sent exactly
+  once") — do not add interaction verification for calls that are
+  incidental implementation detail, which locks the test to today's
+  internal wiring.
+
+## Assertions and determinism
+
+- Use the project's already-adopted assertion style (xUnit's built-in
+  `Assert`, or FluentAssertions if already a dependency) — do not
+  introduce a second assertion library into a project that has
+  standardized on one.
+- Never synchronize with `Thread.Sleep`/`Task.Delay` to wait for an
+  async operation or background work to finish — await the actual
+  `Task`, or use a real synchronization primitive
+  (`TaskCompletionSource`, a cancellation-bounded wait) so the test is
+  deterministic and not flaky under load.
+- Reset/dispose any shared test fixture (`IClassFixture<T>`, a
+  `WebApplicationFactory<TEntryPoint>` for integration tests) between
+  cases that mutate shared state, so one test's leftovers cannot change
+  another's result depending on run order.

package/src/gdskills/bundled/stacks/csharp-dotnet/skills/dotnet-build-fix/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: dotnet-build-fix
+description: "Use when dotnet build/dotnet test fails, or a NuGet restore is broken -- resolves package/target-framework mismatches, compiler errors, nullable-annotation warnings, analyzer/StyleCop findings, and a failing test, with the smallest root-cause fix rather than a suppression."
+triggers:
+  - "dotnet build is failing"
+  - "fix this NuGet package restore error"
+  - "resolve this nullable reference type warning"
+  - "dotnet build analyzer warning"
+  - "StyleCop is failing on this C# file"
+  - "dotnet test is failing, fix the build"
+metadata:
+  origin: authored
+  category: build-fix
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# .NET build fix
+
+Resolve a `dotnet build`/`dotnet test` failure, a NuGet restore error, a
+compiler error, a nullable-reference-type warning, an analyzer/StyleCop
+finding, or a failing test — with the smallest change that fixes the
+actual root cause. `rules/coding-style.mdc` and `rules/security.mdc`
+govern what a "correct" fix looks like; this skill never reaches for a
+suppression instead of a fix.
+
+## Workflow
+
+### Step 1: Reproduce and classify
+
+```bash
+dotnet build
+dotnet test
+```
+
+Read the exact error/warning text and classify it:
+
+- **Compile error** (undefined symbol, type mismatch, wrong overload
+  resolution).
+- **Package/restore** (NuGet version conflict, a `PackageReference`
+  pointing at a version that does not exist, a target-framework
+  mismatch between a project and one of its package dependencies).
+- **Nullable warning** (`CS8600`-`CS8655` range — a possible null
+  reference, an unannotated parameter used where `?` was expected).
+- **Analyzer/style finding** (a Roslyn analyzer, StyleCop, or an
+  `.editorconfig`-driven `IDE`/`CA` rule).
+- **Failing test** (an assertion failure or unhandled exception under
+  `dotnet test`).
+
+### Step 2: Fix by category
+
+**Package/restore:** run `dotnet restore` when the lock file is simply
+stale. For a genuine version conflict, check `dotnet list package
+--include-transitive` to see what is pulling in the conflicting version
+before bumping anything by hand. Only pin a package to an explicit
+version for a real, understood reason (a known-bad release, an
+intentional hold) — never to make a conflict disappear without
+understanding it, and say so in the report either way.
+
+**Compile error:** read the exact overload/type the compiler expected
+versus what was supplied; fix the call site or the signature, whichever
+is actually wrong relative to the feature's intent — do not change a
+public signature just to make one call site compile if other callers
+would break.
+
+**Nullable warning:** fix the actual null path — add a real null check,
+give the value a non-null initializer, or restructure so the compiler's
+flow analysis can see the invariant. Only annotate the type `?` if the
+value can genuinely be null by design. Never resolve the warning with
+the null-forgiving operator (`value!`) as a substitute for an actual
+guard, and never widen the fix into `<Nullable>disable</Nullable>` for
+the file or project.
+
+**Analyzer/StyleCop finding:** fix the underlying issue the rule names
+(the real formatting/ordering/pattern it wants). Never add
+`#pragma warning disable` or a `[SuppressMessage(...)]` attribute whose
+only purpose is to make the analyzer stop complaining without addressing
+what it found.
+
+**Failing test:** read the assertion failure or stack trace; fix the
+production code if the test correctly caught a real bug, or fix the test
+if its expectation was wrong — state which one you concluded and why in
+the report, never silently delete or skip the test to reach green.
+
+### Step 3: Verify
+
+```bash
+dotnet build
+dotnet test
+dotnet format --verify-no-changes
+```
+
+All must exit 0 before reporting done.
+
+### Step 4: Report
+
+```
+Fixed: NuGet version conflict between Package.A 3.0 and Package.B's
+  transitive dependency on Package.A 2.5
+  - Root cause: Package.B pinned an older Package.A that Package.A 3.0's
+    breaking change conflicted with; updated Package.B instead of
+    downgrading Package.A
+  - dotnet build/test/format all pass
+```
+
+State the root cause in one sentence, not just "fixed the error."
+
+## Rules
+
+- Find and fix the smallest change that addresses the actual root
+  cause — never widen a fix beyond what the failure requires.
+- NEVER add `#pragma warning disable` or `[SuppressMessage(...)]` to
+  silence an analyzer/StyleCop finding instead of fixing what it found.
+- NEVER add `<Nullable>disable</Nullable>` (project- or file-wide) or
+  reach for the null-forgiving operator (`value!`) as a substitute for
+  an actual null-safety fix.
+- NEVER pin or downgrade a NuGet package to route around a real
+  incompatibility without understanding and stating why in the report.
+- NEVER delete or skip a failing test to reach a green build.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll add `#pragma warning disable CS8602` around this block" | Silences the finding without fixing the possible-null-dereference it caught; add the actual null check instead |
+| "This nullable warning is annoying, I'll just add `!` here" | The null-forgiving operator tells the compiler to trust you without verifying anything; use it only at a boundary you can justify in a comment, never as a default fix |
+| "I'll just downgrade this package to the version that used to work" | Papers over whatever actually changed without understanding it; check `dotnet list package --include-transitive` and fix the real conflict |
+| "This test keeps failing, I'll mark it `[Fact(Skip = \"flaky\")]`" | Hides a real regression instead of fixing it; find out whether the test or the code is wrong before touching either |
+
+## Verification
+
+Do not report the fix done until all of the following hold:
+
+- `dotnet build`, `dotnet test`, and `dotnet format --verify-no-changes`
+  all exit 0.
+- The change is the smallest one that addresses the stated root cause —
+  no unrelated files touched.
+- No `#pragma warning disable`, `[SuppressMessage(...)]`,
+  `<Nullable>disable</Nullable>`, or unexplained null-forgiving operator
+  was added as part of the fix.
+- The report states the root cause in one sentence, not just "build now
+  passes."