com.wallstop-studios.dxmessaging 2.1.4 → 2.1.5

package/.llm/skills/documentation/skill-file-sizing.md

@@ -0,0 +1,260 @@
+---
+title: "Skill File Sizing Guidelines"
+id: "skill-file-sizing"
+category: "documentation"
+version: "1.0.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: ".llm/skills/specification.md"
+    - path: "scripts/validate-skills.js"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "documentation"
+  - "skills"
+  - "file-organization"
+  - "maintainability"
+  - "llm-context"
+
+complexity:
+  level: "basic"
+  reasoning: "Straightforward guidelines with clear metrics"
+
+impact:
+  performance:
+    rating: "none"
+    details: "No runtime impact, documentation only"
+  maintainability:
+    rating: "high"
+    details: "Properly sized files are easier to maintain and update"
+  testability:
+    rating: "low"
+    details: "Smaller, focused files are easier to validate"
+
+prerequisites:
+  - "Understanding of skill file structure"
+  - "Familiarity with specification.md"
+
+dependencies:
+  packages: []
+  skills:
+    - "documentation-updates"
+
+applies_to:
+  languages:
+    - "Markdown"
+  frameworks: []
+  versions: {}
+
+aliases:
+  - "skill-sizing"
+  - "file-length-limits"
+
+related:
+  - "documentation-updates"
+  - "changelog-management"
+
+status: "stable"
+---
+
+# Skill File Sizing Guidelines
+
+> **One-line summary**: Keep skill files between 200-350 lines for optimal LLM context usage and maintainability.
+
+## Overview
+
+Skill files are designed to provide focused, actionable guidance that LLMs can effectively use during code generation and problem-solving. File size directly impacts how well an LLM can understand and apply the skill content. Files that are too long overwhelm context windows and dilute focus; files that are too short lack sufficient detail for proper application.
+
+This skill documents the sizing requirements for skill files and context documents in the `.llm/` directory.
+
+## Problem Statement
+
+Large skill files create several problems:
+
+- **Context window saturation**: LLMs have limited context windows; overly large files consume disproportionate space
+- **Reduced focus**: Long files often cover too many concepts, making it harder for LLMs to identify relevant guidance
+- **Maintenance burden**: Large files are harder to review, update, and keep accurate
+- **Cognitive overload**: Both humans and LLMs struggle with monolithic documentation
+
+Conversely, files that are too short may lack:
+
+- Sufficient examples to demonstrate patterns
+- Edge case coverage
+- Anti-pattern documentation
+
+## Solution
+
+### Core Concept
+
+Apply strict line count limits with graduated enforcement:
+
+| Range         | Status     | Action                                     |
+| ------------- | ---------- | ------------------------------------------ |
+| < 200 lines   | 📝 Short   | Consider adding more examples or detail    |
+| 200-350 lines | ✅ Ideal   | Target range for skill files               |
+| 351-500 lines | ⚠️ Warning | Consider splitting into focused sub-skills |
+| > 500 lines   | ❌ Error   | Must split; blocks CI/pre-commit           |
+
+### Implementation
+
+Line count validation is automated via `scripts/validate-skills.js`:
+
+```javascript
+const LINE_LIMIT_IDEAL_MIN = 200;
+const LINE_LIMIT_IDEAL_MAX = 350;
+const LINE_LIMIT_HARD_MAX = 500;
+```
+
+Run validation manually:
+
+```bash
+node scripts/validate-skills.js
+```
+
+### Enforcement Points
+
+1. **Pre-commit hook**: Warns on files exceeding 350 lines, blocks on 500+
+1. **CI/CD pipeline**: Fails PRs that introduce files exceeding 500 lines
+1. **Index generation**: Reports line counts in `index.md`
+
+## Variations
+
+### Variation A: Context Files
+
+The main `context.md` file follows the same limits. If it grows too large, extract detailed guidance into category-specific skill files.
+
+> **Note**: `context.md` is excluded from "short file" informational messages since it serves as a high-level summary document that intentionally references other skill files rather than containing exhaustive detail itself.
+
+### Variation B: Specification Files
+
+`specification.md` and `index.md` are exempt from validation but should still aim for reasonable lengths.
+
+## Usage Examples
+
+### Example 1: Splitting a Large Skill
+
+If `object-pooling.md` exceeds 350 lines:
+
+**Before** (one large file):
+
+```text
+.llm/skills/performance/
+└── object-pooling.md (450 lines)
+```
+
+**After** (split by variation):
+
+```text
+.llm/skills/performance/
+├── object-pooling.md (180 lines - core concept)
+├── array-pooling.md (200 lines - array-specific)
+├── collection-pooling.md (220 lines - collections)
+└── stringbuilder-pooling.md (190 lines - StringBuilder)
+```
+
+### Example 2: Organizing Related Skills
+
+Group related skills under a common category with cross-references:
+
+```markdown
+## See Also
+
+- [Array Pooling](./array-pooling.md) - Specialized pooling for arrays
+- [Collection Pooling](./collection-pooling.md) - List and Dictionary pooling
+```
+
+## Anti-Patterns
+
+### ❌ Kitchen Sink Skills
+
+```markdown
+# Everything About Performance
+
+This skill covers pooling, caching, inlining, struct optimization,
+memory alignment, SIMD, async patterns, threading...
+```
+
+**Why it's wrong**: Covers too many unrelated concepts. Split into focused skills.
+
+### ❌ Overly Terse Skills
+
+```markdown
+# Object Pooling
+
+Use pools. Here's how:
+
+`ObjectPool<T>.Get()` / `ObjectPool<T>.Return()`
+
+Done.
+```
+
+**Why it's wrong**: Lacks examples, context, anti-patterns, and edge cases.
+
+### ❌ Excessive Code Duplication
+
+Including the same example code in multiple variations within one file. Extract to a referenced utility or create separate skill files.
+
+## Testing Considerations
+
+Validation is automated:
+
+```bash
+# Run validation
+node scripts/validate-skills.js
+
+# Check output for size warnings/errors
+# ⚠️  size: File has 380 lines (ideal: 200-350)
+# ❌ size: File has 520 lines (max: 500)
+```
+
+## When to Split a Skill
+
+Consider splitting when:
+
+1. **Line count exceeds 350**: The primary trigger
+1. **Multiple distinct variations**: Each variation could stand alone
+1. **Different complexity levels**: Basic vs. advanced usage
+1. **Different use cases**: Unity-specific vs. general .NET
+1. **Tangential content**: Testing guidance, migration guides
+
+## File Organization Strategy
+
+```text
+.llm/skills/{category}/
+├── {main-concept}.md           # Core pattern (200-350 lines)
+├── {concept}-{variation1}.md   # Specific variation
+├── {concept}-{variation2}.md   # Another variation
+└── {concept}-advanced.md       # Advanced usage
+```
+
+Cross-reference using the `related` frontmatter field and `## See Also` sections.
+
+## Performance Notes
+
+File size limits improve:
+
+- **LLM response quality**: Focused context leads to better suggestions
+- **Index generation speed**: Smaller files parse faster
+- **PR review efficiency**: Reviewers can assess changes quickly
+
+## See Also
+
+- [Documentation Updates](./documentation-updates.md)
+- [Changelog Management](./changelog-management.md)
+- [Skill Specification](../specification.md)
+
+## References
+
+- [Skill Specification](../specification.md)
+- Validation script: [scripts/validate-skills.js](../../../scripts/validate-skills.js)
+- Pre-commit config: [.pre-commit-config.yaml](../../../.pre-commit-config.yaml)
+
+## Changelog
+
+| Version | Date       | Changes                                     |
+| ------- | ---------- | ------------------------------------------- |
+| 1.0.0   | 2026-01-22 | Initial version with 200-350 ideal, 500 max |

package/.llm/skills/index.md

@@ -0,0 +1,231 @@
+# Skills Index
+
+> **Auto-generated** on 2026-01-28. Do not edit manually.
+> Run `node scripts/generate-skills-index.js` to regenerate.
+
+---
+
+## Summary
+
+| Metric       | Value |
+| ------------ | ----- |
+| Total Skills | 76    |
+| Categories   | 5     |
+| Unique Tags  | 139   |
+
+---
+
+## Table of Contents
+
+- [Documentation](#documentation) (12)
+- [Performance](#performance) (24)
+- [Scripting](#scripting) (3)
+- [Solid](#solid) (13)
+- [Testing](#testing) (24)
+- [Tag Cloud](#tag-cloud)
+- [All Skills by Complexity](#all-skills-by-complexity)
+
+---
+
+## Documentation
+
+| Skill                                                                                       | Lines  | Complexity | Status    | Performance | Tags                                      |
+| ------------------------------------------------------------------------------------------- | ------ | ---------- | --------- | ----------- | ----------------------------------------- |
+| [Changelog Entry Writing and Anti-Patterns](./documentation/changelog-entry-writing.md)     | ✅ 278 | 🟢 Basic   | ✅ Stable | ○○○○○       | changelog, release-notes, writing         |
+| [Changelog Management](./documentation/changelog-management.md)                             | 📝 191 | 🟢 Basic   | ✅ Stable | ○○○○○       | changelog, documentation, versioning      |
+| [Changelog Release Workflow](./documentation/changelog-release-workflow.md)                 | ✅ 250 | 🟢 Basic   | ✅ Stable | ○○○○○       | changelog, release-workflow, versioning   |
+| [Documentation Code Samples](./documentation/documentation-code-samples.md)                 | ✅ 263 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, code-samples, examples     |
+| [Documentation Style Guide](./documentation/documentation-style-guide.md)                   | 📝 186 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, style, writing             |
+| [Documentation Update Workflow](./documentation/documentation-update-workflow.md)           | 📝 147 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, workflow, checklist        |
+| [Documentation Updates and Maintenance](./documentation/documentation-updates.md)           | 📝 147 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, code-comments, xml-docs    |
+| [External URL Fragment Validation](./documentation/external-url-fragment-validation.md)     | 📝 182 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, links, urls                |
+| [GitHub Actions Version Consistency](./documentation/github-actions-version-consistency.md) | ✅ 204 | 🟢 Basic   | ✅ Stable | ○○○○○       | github-actions, ci-cd, version-management |
+| [Link Quality and External URL Management](./documentation/link-quality-guidelines.md)      | ✅ 268 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, links, urls                |
+| [Skill File Sizing Guidelines](./documentation/skill-file-sizing.md)                        | ✅ 261 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, skills, file-organization  |
+| [XML Documentation Standards](./documentation/documentation-xml-docs.md)                    | 📝 191 | 🟢 Basic   | ✅ Stable | ○○○○○       | documentation, xml-docs, api-reference    |
+
+## Performance
+
+| Skill                                                                                                           | Lines  | Complexity      | Status    | Performance | Tags                                   |
+| --------------------------------------------------------------------------------------------------------------- | ------ | --------------- | --------- | ----------- | -------------------------------------- |
+| [AggressiveInlining for Hot Path Optimization](./performance/aggressive-inlining.md)                            | ✅ 343 | 🟡 Intermediate | ✅ Stable | ●●○○○       | performance, inlining, optimization    |
+| [AggressiveInlining Performance Notes](./performance/aggressive-inlining-performance-notes.md)                  | 📝 95  | 🟡 Intermediate | ✅ Stable | ●●○○○       | performance, inlining, optimization    |
+| [Array Pooling Usage Examples](./performance/array-pooling-usage-examples.md)                                   | 📝 146 | 🟡 Intermediate | ✅ Stable | ●●●○○       | memory, allocation, pooling            |
+| [Array Pooling with ArrayPool and Custom Pools](./performance/array-pooling.md)                                 | ✅ 316 | 🟡 Intermediate | ✅ Stable | ●●●●●       | memory, allocation, pooling            |
+| [Auto-Load Singleton Attribute](./performance/singleton-autoload.md)                                            | 📝 112 | 🟡 Intermediate | ✅ Stable | ●○○○○       | unity, singleton, patterns             |
+| [Cache Builder Configuration](./performance/cache-eviction-builder.md)                                          | ✅ 204 | 🟡 Intermediate | ✅ Stable | ●●●○○       | caching, builder, configuration        |
+| [Cache Eviction Implementation](./performance/cache-eviction-implementation.md)                                 | ✅ 341 | 🟠 Advanced     | ✅ Stable | ●●●○○       | caching, eviction, lru                 |
+| [Collection Pooling with RAII Pattern](./performance/collection-pooling.md)                                     | ✅ 314 | 🟡 Intermediate | ✅ Stable | ●●●○○       | memory, allocation, pooling            |
+| [High-Performance Cache with Eviction Policies](./performance/cache-eviction-policies.md)                       | 📝 177 | 🟠 Advanced     | ✅ Stable | ●●●○○       | caching, memory, performance           |
+| [Object Pooling Anti-Patterns](./performance/object-pooling-anti-patterns.md)                                   | 📝 145 | 🟡 Intermediate | ✅ Stable | ●●●○○       | memory, allocation, pooling            |
+| [Object Pooling for Zero-Allocation Messaging](./performance/object-pooling.md)                                 | ✅ 320 | 🟡 Intermediate | ✅ Stable | ●●●○○       | memory, allocation, garbage-collection |
+| [Object Pooling Usage Examples](./performance/object-pooling-usage-examples.md)                                 | 📝 115 | 🟡 Intermediate | ✅ Stable | ●●●○○       | memory, allocation, pooling            |
+| [Object Pooling Variations](./performance/object-pooling-variations.md)                                         | 📝 148 | 🟡 Intermediate | ✅ Stable | ●●●○○       | memory, allocation, pooling            |
+| [Readonly Struct Cached Hash Performance Notes](./performance/readonly-struct-cached-hash-performance-notes.md) | 📝 92  | 🟡 Intermediate | ✅ Stable | ●●●○○       | performance, struct, hashcode          |
+| [Readonly Struct with Cached Hash for Dictionary Keys](./performance/readonly-struct-cached-hash.md)            | ✅ 338 | 🟡 Intermediate | ✅ Stable | ●●●○○       | performance, struct, hashcode          |
+| [Runtime Singleton Pattern](./performance/singleton-runtime.md)                                                 | 📝 188 | 🟡 Intermediate | ✅ Stable | ●○○○○       | unity, singleton, patterns             |
+| [RuntimeSingleton and ScriptableObject Singleton Patterns](./performance/singleton-patterns.md)                 | 📝 166 | 🟡 Intermediate | ✅ Stable | ●●○○○       | unity, singleton, patterns             |
+| [ScriptableObject Singleton Pattern](./performance/singleton-scriptableobject.md)                               | 📝 178 | 🟡 Intermediate | ✅ Stable | ●○○○○       | unity, singleton, patterns             |
+| [Serializable Dictionary for Unity Inspector](./performance/serializable-dictionary.md)                         | ✅ 282 | 🟡 Intermediate | ✅ Stable | ●○○○○       | unity, serialization, dictionary       |
+| [Serializable Dictionary Property Drawer](./performance/serializable-dictionary-property-drawer.md)             | 📝 148 | 🟡 Intermediate | ✅ Stable | ●●○○○       | unity, serialization, dictionary       |
+| [Serializable Dictionary Usage Examples](./performance/serializable-dictionary-usage-examples.md)               | 📝 136 | 🟡 Intermediate | ✅ Stable | ●●○○○       | unity, serialization, dictionary       |
+| [Singleton Usage Examples](./performance/singleton-usage-examples.md)                                           | 📝 140 | 🟡 Intermediate | ✅ Stable | ●○○○○       | unity, singleton, patterns             |
+| [StringBuilder Pooling for Zero-Allocation String Building](./performance/stringbuilder-pooling.md)             | ✅ 320 | 🟢 Basic        | ✅ Stable | ●●●○○       | memory, allocation, pooling            |
+| [WaitForSeconds and Yield Instruction Pooling](./performance/yield-instruction-pooling.md)                      | ✅ 348 | 🟢 Basic        | ✅ Stable | ●●●○○       | performance, unity, coroutines         |
+
+## Scripting
+
+| Skill                                                                              | Lines  | Complexity      | Status    | Performance | Tags                                      |
+| ---------------------------------------------------------------------------------- | ------ | --------------- | --------- | ----------- | ----------------------------------------- |
+| [Cross-Platform Script Compatibility](./scripting/cross-platform-compatibility.md) | ✅ 225 | 🟡 Intermediate | ✅ Stable | ○○○○○       | cross-platform, case-sensitivity, testing |
+| [PowerShell Scripting Best Practices](./scripting/powershell-best-practices.md)    | ⚠️ 387 | 🟡 Intermediate | ✅ Stable | ○○○○○       | powershell, scripting, regex              |
+| [Shell Scripting Best Practices](./scripting/shell-best-practices.md)              | ✅ 336 | 🟡 Intermediate | ✅ Stable | ○○○○○       | shell, bash, scripting                    |
+
+## Solid
+
+| Skill                                                                                              | Lines  | Complexity      | Status    | Performance | Tags                                 |
+| -------------------------------------------------------------------------------------------------- | ------ | --------------- | --------- | ----------- | ------------------------------------ |
+| [Collection Extension Methods with Performance Documentation](./solid/collection-extensions.md)    | 📝 145 | 🟡 Intermediate | ✅ Stable | ●●●○○       | solid, extensions, collections       |
+| [Collection Extensions: Accessors](./solid/collection-extensions-accessors.md)                     | ✅ 230 | 🟡 Intermediate | ✅ Stable | ●●●○○       | collections, extensions, try-pattern |
+| [Collection Extensions: Shuffle](./solid/collection-extensions-shuffle.md)                         | 📝 145 | 🟢 Basic        | ✅ Stable | ●●○○○       | collections, shuffle, fisher-yates   |
+| [Collection Extensions: Type Specialization](./solid/collection-extensions-type-specialization.md) | 📝 169 | 🟡 Intermediate | ✅ Stable | ●●●○○       | collections, extensions, performance |
+| [Fluent Builder Pattern with Struct Builders](./solid/fluent-builder-pattern.md)                   | ✅ 323 | 🟡 Intermediate | ✅ Stable | ●●○○○       | solid, patterns, builder             |
+| [Fluent Builder Templates and Factories](./solid/fluent-builder-pattern-templates.md)              | 📝 118 | 🟡 Intermediate | ✅ Stable | ●●○○○       | solid, patterns, builder             |
+| [Fluent Builder Usage Examples](./solid/fluent-builder-pattern-usage-examples.md)                  | 📝 129 | 🟡 Intermediate | ✅ Stable | ●●○○○       | solid, patterns, builder             |
+| [IEquatable Implementation for Value Types](./solid/iequatable-implementation.md)                  | ✅ 240 | 🟡 Intermediate | ✅ Stable | ●●●○○       | solid, performance, struct           |
+| [IEquatable Implementation Variants](./solid/iequatable-implementation-variants.md)                | ✅ 202 | 🟡 Intermediate | ✅ Stable | ●●○○○       | solid, performance, struct           |
+| [IEquatable Usage Examples](./solid/iequatable-implementation-usage.md)                            | 📝 112 | 🟡 Intermediate | ✅ Stable | ●●○○○       | solid, performance, struct           |
+| [Try-Pattern API Usage Examples](./solid/try-pattern-apis-usage.md)                                | 📝 137 | 🟢 Basic        | ✅ Stable | ●●○○○       | solid, defensive, api-design         |
+| [Try-Pattern API Variants](./solid/try-pattern-apis-variants.md)                                   | ✅ 234 | 🟢 Basic        | ✅ Stable | ●●○○○       | solid, defensive, api-design         |
+| [Try-Pattern APIs for Defensive Programming](./solid/try-pattern-apis.md)                          | ✅ 221 | 🟢 Basic        | ✅ Stable | ●●●○○       | solid, defensive, api-design         |
+
+## Testing
+
+| Skill                                                                                             | Lines  | Complexity      | Status    | Performance | Tags                                        |
+| ------------------------------------------------------------------------------------------------- | ------ | --------------- | --------- | ----------- | ------------------------------------------- |
+| [Comprehensive Test Coverage Requirements](./testing/comprehensive-test-coverage.md)              | 📝 142 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, coverage, edge-cases               |
+| [Data-Driven Coverage Patterns](./testing/test-coverage-data-driven.md)                           | 📝 173 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, data-driven, nunit                 |
+| [Data-Driven Test Sources](./testing/data-driven-tests-sources.md)                                | ✅ 256 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, parameterized, data-driven         |
+| [Data-Driven Test Usage Patterns](./testing/data-driven-tests-usage.md)                           | 📝 108 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, parameterized, data-driven         |
+| [Data-Driven Tests with TestCaseSource](./testing/data-driven-tests.md)                           | 📝 198 | 🟡 Intermediate | ✅ Stable | ●○○○○       | testing, parameterized, data-driven         |
+| [Git and Parser Robustness in CI/CD](./testing/git-workflow-robustness.md)                        | ⚠️ 370 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, git, ci-cd                         |
+| [Script Test Coverage Requirements](./testing/script-test-coverage.md)                            | ✅ 260 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, scripts, jest                      |
+| [Shared Fixtures: Generic Base](./testing/shared-test-fixtures-generic-base.md)                   | 📝 186 | 🟠 Advanced     | ✅ Stable | ●●●○○       | testing, fixtures, generic                  |
+| [Shared Fixtures: Reference Counting](./testing/shared-test-fixtures-reference-counting.md)       | ✅ 253 | 🟠 Advanced     | ✅ Stable | ●●●○○       | testing, fixtures, reference-counting       |
+| [Shared Test Fixtures with Reference Counting](./testing/shared-test-fixtures.md)                 | 📝 166 | 🟠 Advanced     | ✅ Stable | ●●●○○       | testing, fixtures, performance              |
+| [Test Base Class Cleanup Usage](./testing/test-base-class-cleanup-usage.md)                       | ✅ 219 | 🟡 Intermediate | ✅ Stable | ●○○○○       | testing, cleanup, lifecycle                 |
+| [Test Base Class with Automatic Resource Cleanup](./testing/test-base-class-cleanup.md)           | ✅ 324 | 🟡 Intermediate | ✅ Stable | ●○○○○       | testing, cleanup, lifecycle                 |
+| [Test Categories for Selective Execution](./testing/test-categories.md)                           | ✅ 288 | 🟢 Basic        | ✅ Stable | ●●●○○       | testing, organization, categories           |
+| [Test Category Execution](./testing/test-categories-execution.md)                                 | 📝 143 | 🟢 Basic        | ✅ Stable | ○○○○○       | testing, organization, categories           |
+| [Test Coverage Scenario Categories](./testing/test-coverage-scenario-categories.md)               | ✅ 224 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, coverage, edge-cases               |
+| [Test Diagnostics and Investigation Patterns](./testing/test-diagnostics.md)                      | ✅ 248 | 🟡 Intermediate | ✅ Stable | ●○○○○       | testing, diagnostics, debugging             |
+| [Test Diagnostics Patterns](./testing/test-diagnostics-patterns.md)                               | 📝 190 | 🟡 Intermediate | ✅ Stable | ●○○○○       | testing, diagnostics, logging               |
+| [Test Diagnostics Usage](./testing/test-diagnostics-usage.md)                                     | 📝 197 | 🟡 Intermediate | ✅ Stable | ●○○○○       | testing, diagnostics, logging               |
+| [Test Failure Investigation and Zero-Flaky Policy](./testing/test-failure-investigation.md)       | 📝 120 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, investigation, debugging           |
+| [Test Failure Investigation Procedure](./testing/test-failure-investigation-procedure.md)         | ✅ 217 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, investigation, procedure           |
+| [Test Failure Root Causes and Anti-Patterns](./testing/test-failure-investigation-root-causes.md) | 📝 187 | 🟡 Intermediate | ✅ Stable | ○○○○○       | testing, root-cause-analysis, anti-patterns |
+| [Test Invalid Skill](./testing/test-invalid-skill.md)                                             | 📝 27  | 🔴 Expert       | ✅ Stable | ●●●○○       |                                             |
+| [Test Organization and Assertions](./testing/test-coverage-organization-assertions.md)            | 📝 172 | 🟢 Basic        | ✅ Stable | ○○○○○       | testing, assertions, naming                 |
+| [Unity Test Considerations and Anti-Patterns](./testing/test-coverage-unity-anti-patterns.md)     | ✅ 233 | 🟢 Basic        | ✅ Stable | ○○○○○       | testing, unity, anti-patterns               |
+
+---
+
+## Tag Cloud
+
+`testing`×26 `performance`×15 `unity`×13 `documentation`×10 `solid`×10 `memory`×9 `patterns`×9 `pooling`×9 `allocation`×8 `ci-cd`×8 `nunit`×8 `zero-alloc`×7 `collections`×5 `data-driven`×5 `debugging`×5 `singleton`×5 `struct`×5 `anti-patterns`×4 `builder`×4 `coverage`×4 `dictionary`×4 `fixtures`×4 `versioning`×4 `api-design`×3 `caching`×3 `changelog`×3 `defensive`×3 `diagnostics`×3 `equality`×3 `extensions`×3 `fluent-api`×3 `inspector`×3 `investigation`×3 `keep-a-changelog`×3 `linting`×3 `logging`×3 `markdown`×3 `messaging`×3 `organization`×3 `parameterized`×3 `powershell`×3 `quality`×3 `reference-counting`×3 `serialization`×3 `try-pattern`×3 `api-reference`×2 `arrays`×2 `benchmark`×2 `case-sensitivity`×2 `categories`×2 `ci`×2 `cleanup`×2 `code-comments`×2 `code-samples`×2 `data-structures`×2 `edge-cases`×2 `error-handling`×2 `eviction`×2 `examples`×2 `github-actions`×2 `hashcode`×2 `hot-path`×2 `iequatable`×2 `inlining`×2 `javascript`×2 `lfu`×2 `lifecycle`×2 `links`×2 `linux`×2 `lru`×2 `optimization`×2 `release-notes`×2 `root-cause-analysis`×2 `scripting`×2 `urls`×2 `user-communication`×2 `workflows`×2 `writing`×2 `xml-docs`×2 `accessibility`×1 `accuracy`×1 `architecture`×1 `arraypool`×1 `assertions`×1 `automation`×1 `bash`×1 `best-practices`×1 `boxing`×1 `buffers`×1 `checklist`×1 `clarity`×1 `configuration`×1 `coroutines`×1 `cross-platform`×1 `disposable`×1 `dry`×1 `encoding`×1 `file-organization`×1 `fisher-yates`×1 `flaky-tests`×1 `fragments`×1 `garbage-collection`×1 `generic`×1 `git`×1 `here-strings`×1 `implementation`×1 `jest`×1 `llm-context`×1 `macos`×1 `maintainability`×1 `maintenance`×1 `methodimpl`×1 `naming`×1 `negative-tests`×1 `parsing`×1 `pre-commit`×1 `procedure`×1 `raii`×1 `regex`×1 `release-workflow`×1 `scriptable-object`×1 `scripts`×1 `semantic-versioning`×1 `shared-state`×1 `shell`×1 `shuffle`×1 `skills`×1 `stringbuilder`×1 `strings`×1 `style`×1 `test-cases`×1 `thread-safety`×1 `type-specialization`×1 `validation`×1 `version-management`×1 `windows`×1 `workflow`×1 `yield`×1 `zero-flaky`×1
+
+---
+
+## All Skills by Complexity
+
+### 🟢 Basic
+
+- [Changelog Entry Writing and Anti-Patterns](./documentation/changelog-entry-writing.md) _(documentation)_
+- [Changelog Management](./documentation/changelog-management.md) _(documentation)_
+- [Changelog Release Workflow](./documentation/changelog-release-workflow.md) _(documentation)_
+- [Collection Extensions: Shuffle](./solid/collection-extensions-shuffle.md) _(solid)_
+- [Documentation Code Samples](./documentation/documentation-code-samples.md) _(documentation)_
+- [Documentation Style Guide](./documentation/documentation-style-guide.md) _(documentation)_
+- [Documentation Update Workflow](./documentation/documentation-update-workflow.md) _(documentation)_
+- [Documentation Updates and Maintenance](./documentation/documentation-updates.md) _(documentation)_
+- [External URL Fragment Validation](./documentation/external-url-fragment-validation.md) _(documentation)_
+- [GitHub Actions Version Consistency](./documentation/github-actions-version-consistency.md) _(documentation)_
+- [Link Quality and External URL Management](./documentation/link-quality-guidelines.md) _(documentation)_
+- [Skill File Sizing Guidelines](./documentation/skill-file-sizing.md) _(documentation)_
+- [StringBuilder Pooling for Zero-Allocation String Building](./performance/stringbuilder-pooling.md) _(performance)_
+- [Test Categories for Selective Execution](./testing/test-categories.md) _(testing)_
+- [Test Category Execution](./testing/test-categories-execution.md) _(testing)_
+- [Test Organization and Assertions](./testing/test-coverage-organization-assertions.md) _(testing)_
+- [Try-Pattern API Usage Examples](./solid/try-pattern-apis-usage.md) _(solid)_
+- [Try-Pattern API Variants](./solid/try-pattern-apis-variants.md) _(solid)_
+- [Try-Pattern APIs for Defensive Programming](./solid/try-pattern-apis.md) _(solid)_
+- [Unity Test Considerations and Anti-Patterns](./testing/test-coverage-unity-anti-patterns.md) _(testing)_
+- [WaitForSeconds and Yield Instruction Pooling](./performance/yield-instruction-pooling.md) _(performance)_
+- [XML Documentation Standards](./documentation/documentation-xml-docs.md) _(documentation)_
+
+### 🟡 Intermediate
+
+- [AggressiveInlining for Hot Path Optimization](./performance/aggressive-inlining.md) _(performance)_
+- [AggressiveInlining Performance Notes](./performance/aggressive-inlining-performance-notes.md) _(performance)_
+- [Array Pooling Usage Examples](./performance/array-pooling-usage-examples.md) _(performance)_
+- [Array Pooling with ArrayPool and Custom Pools](./performance/array-pooling.md) _(performance)_
+- [Auto-Load Singleton Attribute](./performance/singleton-autoload.md) _(performance)_
+- [Cache Builder Configuration](./performance/cache-eviction-builder.md) _(performance)_
+- [Collection Extension Methods with Performance Documentation](./solid/collection-extensions.md) _(solid)_
+- [Collection Extensions: Accessors](./solid/collection-extensions-accessors.md) _(solid)_
+- [Collection Extensions: Type Specialization](./solid/collection-extensions-type-specialization.md) _(solid)_
+- [Collection Pooling with RAII Pattern](./performance/collection-pooling.md) _(performance)_
+- [Comprehensive Test Coverage Requirements](./testing/comprehensive-test-coverage.md) _(testing)_
+- [Cross-Platform Script Compatibility](./scripting/cross-platform-compatibility.md) _(scripting)_
+- [Data-Driven Coverage Patterns](./testing/test-coverage-data-driven.md) _(testing)_
+- [Data-Driven Test Sources](./testing/data-driven-tests-sources.md) _(testing)_
+- [Data-Driven Test Usage Patterns](./testing/data-driven-tests-usage.md) _(testing)_
+- [Data-Driven Tests with TestCaseSource](./testing/data-driven-tests.md) _(testing)_
+- [Fluent Builder Pattern with Struct Builders](./solid/fluent-builder-pattern.md) _(solid)_
+- [Fluent Builder Templates and Factories](./solid/fluent-builder-pattern-templates.md) _(solid)_
+- [Fluent Builder Usage Examples](./solid/fluent-builder-pattern-usage-examples.md) _(solid)_
+- [Git and Parser Robustness in CI/CD](./testing/git-workflow-robustness.md) _(testing)_
+- [IEquatable Implementation for Value Types](./solid/iequatable-implementation.md) _(solid)_
+- [IEquatable Implementation Variants](./solid/iequatable-implementation-variants.md) _(solid)_
+- [IEquatable Usage Examples](./solid/iequatable-implementation-usage.md) _(solid)_
+- [Object Pooling Anti-Patterns](./performance/object-pooling-anti-patterns.md) _(performance)_
+- [Object Pooling for Zero-Allocation Messaging](./performance/object-pooling.md) _(performance)_
+- [Object Pooling Usage Examples](./performance/object-pooling-usage-examples.md) _(performance)_
+- [Object Pooling Variations](./performance/object-pooling-variations.md) _(performance)_
+- [PowerShell Scripting Best Practices](./scripting/powershell-best-practices.md) _(scripting)_
+- [Readonly Struct Cached Hash Performance Notes](./performance/readonly-struct-cached-hash-performance-notes.md) _(performance)_
+- [Readonly Struct with Cached Hash for Dictionary Keys](./performance/readonly-struct-cached-hash.md) _(performance)_
+- [Runtime Singleton Pattern](./performance/singleton-runtime.md) _(performance)_
+- [RuntimeSingleton and ScriptableObject Singleton Patterns](./performance/singleton-patterns.md) _(performance)_
+- [Script Test Coverage Requirements](./testing/script-test-coverage.md) _(testing)_
+- [ScriptableObject Singleton Pattern](./performance/singleton-scriptableobject.md) _(performance)_
+- [Serializable Dictionary for Unity Inspector](./performance/serializable-dictionary.md) _(performance)_
+- [Serializable Dictionary Property Drawer](./performance/serializable-dictionary-property-drawer.md) _(performance)_
+- [Serializable Dictionary Usage Examples](./performance/serializable-dictionary-usage-examples.md) _(performance)_
+- [Shell Scripting Best Practices](./scripting/shell-best-practices.md) _(scripting)_
+- [Singleton Usage Examples](./performance/singleton-usage-examples.md) _(performance)_
+- [Test Base Class Cleanup Usage](./testing/test-base-class-cleanup-usage.md) _(testing)_
+- [Test Base Class with Automatic Resource Cleanup](./testing/test-base-class-cleanup.md) _(testing)_
+- [Test Coverage Scenario Categories](./testing/test-coverage-scenario-categories.md) _(testing)_
+- [Test Diagnostics and Investigation Patterns](./testing/test-diagnostics.md) _(testing)_
+- [Test Diagnostics Patterns](./testing/test-diagnostics-patterns.md) _(testing)_
+- [Test Diagnostics Usage](./testing/test-diagnostics-usage.md) _(testing)_
+- [Test Failure Investigation and Zero-Flaky Policy](./testing/test-failure-investigation.md) _(testing)_
+- [Test Failure Investigation Procedure](./testing/test-failure-investigation-procedure.md) _(testing)_
+- [Test Failure Root Causes and Anti-Patterns](./testing/test-failure-investigation-root-causes.md) _(testing)_
+
+### 🟠 Advanced
+
+- [Cache Eviction Implementation](./performance/cache-eviction-implementation.md) _(performance)_
+- [High-Performance Cache with Eviction Policies](./performance/cache-eviction-policies.md) _(performance)_
+- [Shared Fixtures: Generic Base](./testing/shared-test-fixtures-generic-base.md) _(testing)_
+- [Shared Fixtures: Reference Counting](./testing/shared-test-fixtures-reference-counting.md) _(testing)_
+- [Shared Test Fixtures with Reference Counting](./testing/shared-test-fixtures.md) _(testing)_
+
+### 🔴 Expert
+
+- [Test Invalid Skill](./testing/test-invalid-skill.md) _(testing)_
+
+---
+
+_Generated by `scripts/generate-skills-index.js`_

package/.llm/skills/performance/aggressive-inlining-performance-notes.md

@@ -0,0 +1,94 @@
+---
+title: "AggressiveInlining Performance Notes"
+id: "aggressive-inlining-performance-notes"
+category: "performance"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/DataStructure/ImmutableBitSet.cs"
+      lines: "55-99"
+    - path: "Runtime/Core/DataStructure/BitSet.cs"
+      lines: "589-613"
+    - path: "Runtime/Core/OneOf/FastOneOf.cs"
+      lines: "129-196"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "performance"
+  - "inlining"
+  - "optimization"
+  - "benchmark"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires reading JIT behavior and benchmark results"
+
+impact:
+  performance:
+    rating: "medium"
+    details: "Provides context on when inlining is measurable"
+  maintainability:
+    rating: "low"
+    details: "Informational only"
+  testability:
+    rating: "none"
+    details: "No test impact"
+
+prerequisites:
+  - "Understanding of JIT inlining"
+
+dependencies:
+  packages: []
+  skills:
+    - "aggressive-inlining"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+    dotnet: ">=netstandard2.0"
+
+aliases:
+  - "Inlining benchmarks"
+
+related:
+  - "aggressive-inlining"
+
+status: "stable"
+---
+
+# AggressiveInlining Performance Notes
+
+> **One-line summary**: Benchmark and JIT behavior notes for aggressive inlining decisions.
+
+## Overview
+
+This skill captures benchmark results and JIT behavior that inform inlining decisions.
+
+## Solution
+
+Use the notes below to decide when AggressiveInlining provides measurable wins.
+
+## Performance Notes
+
+### Benchmark: 10M Dictionary Lookups
+
+| Approach                   | Time    |
+| -------------------------- | ------- |
+| Without AggressiveInlining | 142ms   |
+| With AggressiveInlining    | 98ms    |
+| **Improvement**            | **31%** |
+
+### JIT Behavior
+
+- **Default**: JIT inlines methods < 32 IL bytes
+- **AggressiveInlining**: JIT tries harder, may inline larger methods
+- **Not a guarantee**: JIT can still refuse (virtual, try-catch, etc.)