@cratis/pi 7.101.0 → 7.103.0

package/package/corpus/skills/analyzing-dotnet-performance/references/io-and-serialization.md

@@ -0,0 +1,135 @@
+# I/O, Serialization & General Patterns
+
+## Contents
+
+- Use HttpCompletionOption.ResponseHeadersRead for Streaming
+- Use Async FileStream Operations
+- Use Memory\<byte\> Overloads for Stream.ReadAsync/WriteAsync
+- Use Span-Based TryFormat for Number Formatting
+- Use static readonly for Runtime Devirtualization
+- Avoid Explicit Static Constructors — Use Field Initializers
+- Detection
+  - Patterns Requiring Manual Review
+
+### Use HttpCompletionOption.ResponseHeadersRead for Streaming
+🟡 **DO** use `ResponseHeadersRead` when downloading large responses | .NET Core 3.0+
+
+❌
+```csharp
+var response = await client.GetAsync(uri);
+```
+✅
+```csharp
+using var response = await client.GetAsync(uri, HttpCompletionOption.ResponseHeadersRead);
+using var stream = await response.Content.ReadAsStreamAsync();
+await stream.CopyToAsync(destinationStream);
+```
+
+**Impact: ~2x faster for large downloads (10MB+), dramatically reduced memory usage.**
+
+### Use Async FileStream Operations
+🟡 **DO** use `FileStream` with `useAsync: true` for scalable file I/O | .NET 6+
+
+❌
+```csharp
+using var fs = new FileStream(path, FileMode.Open);
+```
+✅
+```csharp
+await using var fs = new FileStream(path, FileMode.Open, FileAccess.Read,
+    FileShare.Read, bufferSize: 4096, useAsync: true);
+
+byte[] buffer = new byte[1024];
+while (await fs.ReadAsync(buffer) != 0) { /* process */ }
+```
+
+**Impact: Up to 3x faster async reads; allocation reduced from megabytes to hundreds of bytes.**
+
+### Use Memory\<byte\> Overloads for Stream.ReadAsync/WriteAsync
+🟡 **DO** use `Memory<byte>`-based stream overloads instead of `byte[]` overloads | .NET 5+
+
+❌
+```csharp
+await stream.ReadAsync(buffer, 0, buffer.Length);
+await stream.WriteAsync(buffer, 0, buffer.Length);
+```
+✅
+```csharp
+await stream.ReadAsync(buffer.AsMemory());
+await stream.WriteAsync(buffer.AsMemory());
+```
+
+**Impact: Eliminates ~72 KB allocation per 1,000 read/write pairs on NetworkStream.**
+
+### Use Span-Based TryFormat for Number Formatting
+🟡 **DO** use `TryFormat` to format numbers into `Span<char>` buffers | .NET Core 2.1+
+
+❌
+```csharp
+string formatted = value.ToString();
+destination.Write(formatted);
+```
+✅
+```csharp
+Span<char> buffer = stackalloc char[20];
+if (value.TryFormat(buffer, out int charsWritten))
+    destination.Write(buffer[..charsWritten]);
+```
+
+**Impact: Int32.ToString() ~2x faster in .NET Core 2.1, Int32 parsing ~5x faster in .NET Core 3.0.**
+
+### Use static readonly for Runtime Devirtualization
+🟡 **DO** store implementations in `static readonly` fields for JIT devirtualization | .NET Core 3.0+
+
+❌
+```csharp
+private static Base s_impl = new DerivedImpl();
+s_impl.Process();
+```
+✅
+```csharp
+private static readonly Base s_impl = new DerivedImpl();
+s_impl.Process();
+
+private static readonly bool s_feature =
+    Environment.GetEnvironmentVariable("Feature") == "1";
+```
+
+**Impact: Virtual call eliminated entirely — can be inlined to zero overhead. Dead code elimination in tier 1.**
+
+### Avoid Explicit Static Constructors — Use Field Initializers
+🟡 **AVOID** explicit `static` constructors when field initializers suffice | .NET Core 3.0+
+
+❌
+```csharp
+class Foo
+{
+    static readonly int s_value;
+    static Foo() { s_value = ComputeValue(); }
+}
+```
+✅
+```csharp
+class Foo
+{
+    static readonly int s_value = ComputeValue();
+}
+```
+
+**Impact: Enables better JIT optimization and reduces potential lock overhead on static method access.**
+
+## Detection
+
+Scan recipes for I/O and serialization anti-patterns. Run these and report exact counts.
+
+```bash
+# new HttpClient() (socket exhaustion risk)
+grep -rn --include='*.cs' 'new HttpClient(' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# new JsonSerializerOptions() not cached (592x slower in .NET 6)
+grep -rn --include='*.cs' 'new JsonSerializerOptions' --exclude-dir=bin --exclude-dir=obj . | grep -v 'static\|readonly' | wc -l
+```
+
+### Patterns Requiring Manual Review
+
+- **`JsonSerializer.Serialize/Deserialize` without source-gen context**: Can't determine from grep if a context parameter is passed

package/package/corpus/skills/analyzing-dotnet-performance/references/memory-and-strings.md

@@ -0,0 +1,219 @@
+# Memory & String Patterns
+
+## Contents
+
+- Use ReadOnlySpan\<byte\> for Constant Byte Data
+- Use stackalloc for Small Temporary Buffers
+- Use Span.TryWrite for Allocation-Free Interpolation
+- Use Span.Split() for Zero-Allocation Splitting
+- Use UTF8 String Literals (u8 suffix)
+- Use ReadOnlySpan\<char\> Pattern Matching with switch
+- Use params ReadOnlySpan\<T\> to Eliminate Array Allocations
+- Avoid Chained String-Returning Operations
+- Cache char.ToString() for Known Character Sets
+- Detection
+  - Patterns Requiring Manual Review
+
+### Use ReadOnlySpan\<byte\> for Constant Byte Data
+🟡 **DO** assign constant byte arrays to `ReadOnlySpan<byte>` | .NET 5+
+
+❌
+```csharp
+byte[] data = new byte[] { 0x48, 0x65, 0x6C, 0x6C, 0x6F };
+```
+✅
+```csharp
+ReadOnlySpan<byte> data = [0x48, 0x65, 0x6C, 0x6C, 0x6F];
+ReadOnlySpan<int> primes = [2, 3, 5, 7, 11, 13];
+```
+
+**Impact: ~100x faster access than static byte[] field, zero allocation.**
+
+### Use stackalloc for Small Temporary Buffers
+🟡 **DO** use `stackalloc` for small, fixed-size temporary buffers | .NET Core+
+
+❌
+```csharp
+char[] buffer = new char[64];
+guid.TryFormat(buffer, out int written);
+```
+✅
+```csharp
+Span<char> buffer = stackalloc char[64];
+guid.TryFormat(buffer, out int written);
+```
+
+**Impact: Zero heap allocation, no GC pressure, instant alloc/dealloc.**
+
+### Use Span.TryWrite for Allocation-Free Interpolation
+🟡 **DO** use `MemoryExtensions.TryWrite` to format into `Span<char>` buffers | .NET 6+
+
+❌
+```csharp
+string formatted = $"Date: {dt:R}";
+destination.Write(formatted);
+```
+✅
+```csharp
+Span<char> buffer = stackalloc char[64];
+buffer.TryWrite($"Date: {dt:R}", out int charsWritten);
+```
+
+**Impact: Zero heap allocation for formatting operations.**
+
+### Use Span.Split() for Zero-Allocation Splitting
+🟡 **DO** use `MemoryExtensions.Split` for allocation-free string splitting | .NET 9+
+
+❌
+```csharp
+string[] parts = input.Split(',');
+```
+✅
+```csharp
+foreach (Range range in input.AsSpan().Split(','))
+{
+    ReadOnlySpan<char> segment = input.AsSpan(range);
+}
+```
+
+**Impact: 208 bytes → 0 bytes per split, 2x faster.**
+
+### Use UTF8 String Literals (u8 suffix)
+🟡 **DO** use the `u8` suffix for compile-time UTF8 `ReadOnlySpan<byte>` | .NET 7+
+
+❌
+```csharp
+byte[] header = Encoding.UTF8.GetBytes("Content-Type");
+```
+✅
+```csharp
+ReadOnlySpan<byte> header = "Content-Type"u8;
+```
+
+**Impact: 17ns → 0.006ns — eliminates runtime transcoding entirely.**
+
+### Use ReadOnlySpan\<char\> Pattern Matching with switch
+🟡 **DO** use `switch` on `ReadOnlySpan<char>` for allocation-free string matching | C# 11+
+
+❌
+```csharp
+switch (attr.Value.Trim()) { case "preserve": /* ... */ break; }
+```
+✅
+```csharp
+switch (attr.Value.AsSpan().Trim())
+{
+    case "preserve": return Preserve;
+    case "default": return Default;
+}
+```
+
+**Impact: Eliminates string allocation from Trim() in switch-based dispatch.**
+
+### Use params ReadOnlySpan\<T\> to Eliminate Array Allocations
+🟡 **DO** add `params ReadOnlySpan<T>` overloads to library methods | C# 13 / .NET 9+
+
+❌
+```csharp
+public static void Log(params string[] messages) { /* ... */ }
+Log("Starting", "Processing", "Done");
+```
+✅
+```csharp
+public static void Log(params ReadOnlySpan<string> messages) { /* ... */ }
+Log("Starting", "Processing", "Done");
+```
+
+**Impact: Eliminates params array allocation. E.g., Path.Join with 5+ segments saves 64 bytes per call.**
+
+### Avoid Chained String-Returning Operations
+🟡 **AVOID** chains of 3+ string-returning method calls that each allocate intermediates | .NET Core+
+
+**Pattern 1: Chained .Replace() calls**
+
+❌
+```csharp
+string result = input.Replace("a", "b").Replace("c", "d").Replace("e", "f");
+```
+✅
+```csharp
+var sb = new StringBuilder(input.Length);
+// single pass replacing all patterns
+```
+
+**Pattern 2: Chained Regex.Replace() calls**
+
+❌
+```csharp
+public static string Underscore(this string input) =>
+    Regex3.Replace(Regex2.Replace(Regex1.Replace(input, "$1_$2"), "$1_$2"), "_").ToLower();
+```
+✅
+```csharp
+return string.Create(totalLength, state, (span, s) => { /* write directly */ });
+```
+
+**Pattern 3: += string concatenation in loops**
+
+❌
+```csharp
+string result = "";
+foreach (var part in parts)
+    result += separator + part;
+```
+✅
+```csharp
+var sb = new StringBuilder();
+foreach (var part in parts)
+    sb.Append(separator).Append(part);
+return sb.ToString();
+```
+
+**Impact: Eliminates N-1 intermediate string allocations per chain. For `+=` in loops, eliminates O(n²) total allocation.**
+
+### Cache char.ToString() for Known Character Sets
+🟡 **DO** cache `char.ToString()` results when the set of characters is small and known | .NET Core+
+
+❌
+```csharp
+return symbol.ToString();
+
+foreach (var prefix in UnitPrefixes)
+    input = input.Replace(prefix.Value.Name, prefix.Key.ToString());
+```
+✅
+```csharp
+private static readonly FrozenDictionary<char, string> s_charStrings =
+    new Dictionary<char, string>
+    {
+        ['k'] = "k", ['M'] = "M", ['G'] = "G",
+    }.ToFrozenDictionary();
+
+return s_charStrings[symbol];
+```
+
+**Impact: Eliminates one string allocation per char.ToString() call. Significant when called in loops or on hot paths.**
+
+## Detection
+
+Scan recipes for memory and string anti-patterns. Run these and report exact counts.
+
+```bash
+# .ToLower()/.ToUpper() without culture parameter (allocates + culture-sensitive)
+grep -rn --include='*.cs' -E '\.(ToLower|ToUpper)\(\)' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# Chained .Replace( calls (3+ on one line — intermediate string allocations)
+grep -rn --include='*.cs' '\.Replace(.*\.Replace(.*\.Replace(' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# params in method signatures (array allocation per call)
+grep -rn --include='*.cs' 'params ' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# LINQ on strings — .All/.Any on IEnumerable<char> (replace with foreach loop)
+grep -rn --include='*.cs' -E '\.(All|Any)\(char\.' --exclude-dir=bin --exclude-dir=obj . | wc -l
+```
+
+### Patterns Requiring Manual Review
+
+- **Boxing via string.Format**: Can't determine argument types from grep — needs type analysis
+- **`+=` string concatenation in loops**: `+=` matches all types (int, list, event, string) — needs type context to confirm string
+- **`char.ToString()`**: Requires knowing the variable type is `char` — not reliably greppable

package/package/corpus/skills/analyzing-dotnet-performance/references/regex-patterns.md

@@ -0,0 +1,95 @@
+# Regex Patterns
+
+### Choose the Right Regex Engine Mode
+🟡 **DO** use `[GeneratedRegex]` for all static regex patterns, but never remove `NonBacktracking` if present | .NET 7+
+
+❌
+```csharp
+var r = new Regex(dynamicPattern, RegexOptions.Compiled);
+```
+✅
+```csharp
+[GeneratedRegex("pattern")]
+private static partial Regex MyRegex();
+
+var safe = new Regex(untrustedPattern, RegexOptions.NonBacktracking);
+
+var oneOff = new Regex("pattern");
+```
+
+**Impact: Source generator is always beneficial for static patterns. NonBacktracking prevents O(2^N) worst case — never remove it if present.**
+
+### Use IsMatch When You Only Need a Boolean Result
+🟡 **DO** use `IsMatch` instead of `Match(...).Success` | .NET 7+
+
+❌
+```csharp
+bool found = Regex.Match(input, pattern).Success;
+```
+✅
+```csharp
+bool found = Regex.IsMatch(input, pattern);
+```
+
+**Impact: Avoids Match object allocation; with NonBacktracking, ~3x faster by skipping capture computation.**
+
+### Use Regex.Count/EnumerateMatches Instead of Matches
+🟡 **DO** use `Count()` and `EnumerateMatches()` for allocation-free match processing | .NET 7+
+
+❌
+```csharp
+int count = 0;
+Match m = regex.Match(text);
+while (m.Success) { count++; m = m.NextMatch(); }
+```
+✅
+```csharp
+int count = regex.Count(text);
+
+foreach (ValueMatch m in Regex.EnumerateMatches(text, @"\b\w+\b"))
+{
+    ReadOnlySpan<char> word = text.AsSpan(m.Index, m.Length);
+}
+```
+
+**Impact: ~3x faster than Match/NextMatch with NonBacktracking. Zero allocations for both Count and EnumerateMatches.**
+
+### Use Span-Based Regex APIs for Allocation-Free Matching
+🟡 **DO** use `ReadOnlySpan<char>` overloads for regex matching on spans | .NET 7+
+
+❌
+```csharp
+string sub = largeBuffer.Substring(start, length);
+bool found = Regex.IsMatch(sub, pattern);
+```
+✅
+```csharp
+ReadOnlySpan<char> text = largeBuffer.AsSpan(start, length);
+foreach (ValueMatch m in Regex.EnumerateMatches(text, @"\b\w+\b"))
+{
+    ReadOnlySpan<char> word = text.Slice(m.Index, m.Length);
+}
+```
+
+**Impact: Eliminates string allocations when working with spans — particularly valuable in high-throughput parsing pipelines.**
+
+## Detection
+
+Scan recipes for regex anti-patterns. Run these and report exact counts.
+
+```bash
+# Compiled regex count (startup cost budget — compare ratio to GeneratedRegex)
+grep -rn --include='*.cs' 'RegexOptions.Compiled' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# GeneratedRegex count (already optimized — verify the inverse)
+grep -rn --include='*.cs' 'GeneratedRegex' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# Uncached new Regex() calls (construction cost per call)
+grep -rn --include='*.cs' 'new Regex(' --exclude-dir=bin --exclude-dir=obj . | wc -l
+```
+
+When `RegexOptions.Compiled` appears inside a class constructor or field initializer of an instantiated class (not a static singleton), count how many instances of that class are created at startup to determine total compiled regex budget. For example, if a `Rule` class compiles a regex in its constructor and 122 rules are registered, that is 122 compiled regexes at startup.
+
+### Patterns Requiring Manual Review
+
+- **`new Regex(` uncached**: Field assignment may span multiple lines — grep on one line is unreliable. Verify that matched instances are stored in `static readonly` fields or `[GeneratedRegex]`.

package/package/corpus/skills/analyzing-dotnet-performance/references/structural-patterns.md

@@ -0,0 +1,38 @@
+# Structural Patterns
+
+Patterns detected by the **absence** of a keyword or interface. These require codebase-wide counting scans, not single-file matching.
+
+### Seal Classes for Devirtualization
+🟡 **DO** seal all leaf classes (those not subclassed) | .NET Core 3.0+
+
+Sealing lets the JIT devirtualize/inline virtual calls and use pointer comparison for type checks. Every non-abstract, non-static class that is not subclassed should be sealed. **Cratis qualification:** Never seal public types of a published framework/library package: doing so is a breaking change, and Cratis framework repositories treat public API changes as semver.
+
+**Detection:** This is an absence pattern — scan for classes that are NOT sealed.
+
+```bash
+# Count unsealed (non-abstract, non-static) classes
+grep -rn --include='*.cs' -E '^\s*((public|internal|private|protected|file)\s+)?(partial\s+)?class ' --exclude-dir=bin --exclude-dir=obj . | grep -v 'sealed' | grep -v 'abstract' | grep -v 'static' | wc -l
+
+# Count already-sealed classes (verify the inverse)
+grep -rn --include='*.cs' 'sealed class' --exclude-dir=bin --exclude-dir=obj . | wc -l
+```
+
+**Exclusions:** Do not seal classes that are subclassed elsewhere in the codebase. Identifying base classes requires manual review — grep for `: ClassName` patterns and cross-reference, but expect false positives from interface implementations and generic constraints.
+
+❌
+```csharp
+internal class MyHandler : Base
+{ public override int Run() => 42; }
+```
+✅
+```csharp
+internal sealed class MyHandler : Base
+{ public override int Run() => 42; }
+```
+
+**Impact: Virtual calls up to 500x faster; type checks ~25x faster. Severity scales with count.**
+
+**Scale-based severity:**
+- 1-10 unsealed leaf classes → ℹ️ Info
+- 11-50 unsealed leaf classes → 🟡 Moderate
+- 50+ unsealed leaf classes → 🟡 Moderate (elevated priority)

package/package/corpus/skills/binlog-generation/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) .NET Foundation and Contributors
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package/corpus/skills/binlog-generation/NOTICE

@@ -0,0 +1,22 @@
+Generate Binary Logs
+Copyright (c) .NET Foundation and Contributors
+Licensed under the MIT License. See LICENSE.
+
+Upstream source: https://github.com/dotnet/skills/blob/a6bf43ab61967c30919334986515163ab24d7635/plugins/dotnet-msbuild/skills/binlog-generation/SKILL.md
+
+Changes made by Cratis:
+
+LICENSE:
+- Copy upstream MIT license and copyright verbatim.
+
+SKILL.md:
+- Remove the SDK version from the description; the 17.12 floor stays in the body.
+- Normalize frontmatter serialization, add MIT license where absent; preserve name and description.
+- Correct the binlog {} placeholder SDK/MSBuild minimum in description and body.
+- Add marked modification/source comment and applicability/Cratis precedence line with the skill-specific safety, ownership or compatibility caveat.
+- Render unimported binlog-failure-analysis routing reference as plain topic text.
+- Render unimported build-perf-diagnostics routing reference as plain topic text.
+- Correct the binlog {} placeholder SDK/MSBuild minimum.
+- Rewrite the description to the Cratis shape (what it does, Use when, Not for) and drop references to skills that are not part of this corpus.
+
+NOTICE: Add this attribution, change list, and any download/execution disclosure.

package/package/corpus/skills/binlog-generation/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: binlog-generation
+description: 'Generates MSBuild binary logs (binlogs) by adding /bl:{} to dotnet build, test, pack, publish, or restore commands, capturing a full build trace for later investigation. Use when a build error or build-performance problem needs a binlog and none exists. The {} placeholder needs a recent MSBuild; PowerShell must quote the switch as ''-bl:{}''. Not for analyzing an existing binlog or measuring build performance (use the msbuild skill) or for non-MSBuild build systems such as npm, Maven, or CMake.'
+license: MIT
+---
+
+<!-- Modified by Cratis from dotnet's original (MIT): frontmatter, applicability, navigation and the changes listed in NOTICE. Upstream: https://github.com/dotnet/skills (plugins/dotnet-msbuild/skills/binlog-generation/SKILL.md; see NOTICE) -->
+
+# Generate Binary Logs
+
+Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ. Binlogs embed project and imported file contents: keep them local and task-scoped.
+
+**Pass the `/bl` switch when running any MSBuild-based command.** This is a non-negotiable requirement for all .NET builds.
+
+## Commands That Require /bl
+
+You MUST add the `/bl:{}` flag to:
+- `dotnet build`
+- `dotnet test`
+- `dotnet pack`
+- `dotnet publish`
+- `dotnet restore`
+- `msbuild` or `msbuild.exe`
+- Any other command that invokes MSBuild
+
+## Preferred: Use `{}` for Automatic Unique Names
+
+> **Note:** The `{}` placeholder requires MSBuild 17.12+ / .NET 9.0.100 SDK or later.
+
+The `{}` placeholder in the binlog filename is replaced by MSBuild with a unique identifier, guaranteeing no two builds ever overwrite each other — without needing to track or check existing files.
+
+```bash
+# Every invocation produces a distinct file automatically
+dotnet build /bl:{}
+dotnet test /bl:{}
+dotnet build --configuration Release /bl:{}
+```
+
+**PowerShell requires quoting the complete switch:**
+
+```powershell
+# Keep the literal {} placeholder in one argument
+dotnet build '-bl:{}'
+dotnet test '-bl:{}'
+```
+
+## Why This Matters
+
+1. **Unique names prevent overwrites** - You can always go back and analyze previous builds
+2. **Failure analysis** - When a build fails, the binlog is already there for immediate analysis
+3. **Comparison** - You can compare builds before and after changes
+4. **No re-running builds** - You never need to re-run a failed build just to generate a binlog
+
+## Examples
+
+```bash
+# ✅ CORRECT - {} generates a unique name automatically (bash/cmd)
+dotnet build /bl:{}
+dotnet test /bl:{}
+
+# ✅ CORRECT - quote the complete PowerShell argument
+dotnet build '-bl:{}'
+dotnet test '-bl:{}'
+
+# ❌ WRONG - Missing /bl flag entirely
+dotnet build
+dotnet test
+
+# ❌ WRONG - No filename (overwrites the same msbuild.binlog every time)
+dotnet build /bl
+dotnet build /bl
+```
+
+## One build = one binlog
+
+Add `/bl:{}` to **every** MSBuild invocation separately — never reuse a name and
+never rely on bare `/bl`:
+
+- Building several configurations, projects, or retrying a failed build? Each
+  command still gets its own `/bl:{}` so the logs never overwrite each other.
+
+```bash
+dotnet build -c Debug   /bl:{}   # unique file
+dotnet build -c Release /bl:{}   # another unique file
+```
+
+## Verify the binlog exists
+
+After the build, confirm a `.binlog` was actually produced before moving on to
+analysis — a build that fails *before* MSBuild starts (e.g. a bad argument)
+writes no binlog:
+
+```bash
+ls -1 *.binlog       # bash
+dir /b *.binlog      # Windows cmd
+```
+
+```powershell
+Get-ChildItem *.binlog   # PowerShell
+```
+
+Note the resulting path so binlog failure analysis or build perf diagnostics
+can consume it.
+
+## When a Specific Filename Is Required
+
+If the binlog filename needs to be known upfront (e.g., for CI artifact upload), or if `{}` is not available in the installed MSBuild version, pick a name that won't collide with existing files:
+
+1. Check for existing `*.binlog` files in the directory
+2. Choose a name not already taken (e.g., by incrementing a counter from the highest existing number)
+
+```bash
+# Example: directory contains 3.binlog — use 4.binlog
+dotnet build /bl:4.binlog
+```
+
+## Cleaning the Repository
+
+When cleaning the repository with `git clean`, **always exclude binlog files** to preserve your build history:
+
+```bash
+# ✅ CORRECT - Exclude binlog files from cleaning
+git clean -fdx -e "*.binlog"
+
+# ❌ WRONG - This deletes binlog files (they're usually in .gitignore)
+git clean -fdx
+```
+
+This is especially important when iterating on build fixes - you need the binlogs to analyze what changed between builds.

package/package/corpus/skills/check-bin-obj-clash/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) .NET Foundation and Contributors
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.