com.wallstop-studios.dxmessaging 2.1.6 → 2.1.8

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

@@ -1,260 +0,0 @@
----
-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/github-actions/git-renormalize-patterns.md

@@ -1,231 +0,0 @@
----
-title: "Git Renormalize Pattern Validation"
-id: "git-renormalize-patterns"
-category: "github-actions"
-version: "1.0.0"
-created: "2026-01-28"
-updated: "2026-01-28"
-
-source:
-  repository: "wallstop/DxMessaging"
-  files:
-    - path: ".github/workflows/"
-  url: "https://github.com/wallstop/DxMessaging"
-
-tags:
-  - "github-actions"
-  - "git"
-  - "ci-cd"
-  - "line-endings"
-  - "gitattributes"
-
-complexity:
-  level: "intermediate"
-  reasoning: "Requires understanding of git pathspecs, gitattributes, and CI failure modes"
-
-impact:
-  performance:
-    rating: "low"
-    details: "No performance impact; this is about correctness"
-  maintainability:
-    rating: "high"
-    details: "Prevents CI failures and ensures pattern synchronization"
-  testability:
-    rating: "low"
-    details: "Validated by actionlint and manual file existence checks"
-
-prerequisites:
-  - "Understanding of git pathspec patterns"
-  - "Familiarity with .gitattributes line ending normalization"
-  - "Knowledge of GitHub Actions workflow structure"
-
-dependencies:
-  packages: []
-  skills:
-    - "workflow-consistency"
-    - "cross-platform-compatibility"
-
-applies_to:
-  languages:
-    - "YAML"
-  frameworks:
-    - "GitHub Actions"
-  versions:
-    github-actions: "current"
-
-aliases:
-  - "git add renormalize"
-  - "pathspec validation"
-  - "line ending normalization"
-
-related:
-  - "workflow-consistency"
-  - "cross-platform-compatibility"
-  - "git-workflow-robustness"
-
-status: "stable"
----
-
-# Git Renormalize Pattern Validation
-
-> **One-line summary**: Ensure `git add --renormalize` patterns match actual repository
-> files to prevent CI failures from unmatched pathspecs.
-
-## Overview
-
-The `git add --renormalize` command applies `.gitattributes` normalization rules to files
-matching specified patterns. This command **fails with exit code 128** when a pathspec
-pattern matches zero files. This skill documents best practices for pattern validation
-and synchronization across workflow sections.
-
-## Solution
-
-Apply these requirements when using `git add --renormalize` in CI:
-
-1. **Use per-extension loops** (REQUIRED) - Process each extension separately with existence checks
-1. **Validate patterns** match at least one file in the repository
-1. **Synchronize patterns** between `git add --renormalize`, `file_pattern`, and path triggers
-
-### Required Pattern: Per-Extension Loop
-
-**ALWAYS** use this pattern when renormalizing multiple file types:
-
-```bash
-# REQUIRED: Per-extension loop with existence check
-# yaml excluded: dotfiles match git ls-files but not git add globs
-for ext in cs md json asmdef yml; do
-  if git ls-files "*.$ext" "**/*.$ext" | grep -q .; then
-    git add --renormalize -- "*.$ext" "**/*.$ext"
-  fi
-done
-```
-
-**NEVER** use single-line multi-pattern commands (fails with exit 128 if any pattern matches no files):
-
-```bash
-# FORBIDDEN: Fails if ANY pattern matches no files
-git add --renormalize -- '*.md' '**/*.md' '*.json' '**/*.json'
-```
-
-## The Problem
-
-When `git add --renormalize` is given a pattern that matches no files, it fails with exit code 128:
-
-```bash
-fatal: pathspec '*.markdown' did not match any files
-```
-
-### Dotfile Glob Behavior Difference
-
-**CRITICAL**: `git ls-files` matches dotfiles but `git add` does not:
-
-```bash
-git ls-files "*.yaml"              # Returns: .pre-commit-config.yaml
-git add --renormalize -- "*.yaml"  # FAILS: pathspec did not match any files
-```
-
-**Solution**: Exclude `yaml` from extension loops since `.yaml` files are typically dotfiles.
-Use `yml` for non-dotfile YAML files.
-
-**Generalized rule**: Exclude any extension when ALL tracked files of that extension are
-dotfiles. Verify with: `git ls-files "*.$ext" "**/*.$ext"` — if all results start with `.`,
-exclude that extension.
-
-### `file_pattern` in `git-auto-commit-action`
-
-The same dotfile limitation applies to `file_pattern`:
-
-```yaml
-# CORRECT: Exclude yaml if all .yaml files are dotfiles
-file_pattern: "**/*.md **/*.json **/*.yml"
-```
-
-## Command Behavior
-
-| Scenario                     | Exit Code |
-| ---------------------------- | --------- |
-| All patterns match files     | 0         |
-| Any pattern matches no files | 128       |
-| No `.gitattributes` rules    | 0         |
-
-## Best Practices
-
-### Validate Patterns Match Actual Files
-
-```bash
-# Count files by extension
-git ls-files | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -10
-
-# Find all unique extensions
-git ls-files | grep -E '\.[^/]+$' | sed 's/.*\./\./' | sort -u
-```
-
-### Keep Workflow Triggers Synchronized
-
-```yaml
-# GOOD: Only patterns that match existing files
-on:
-  pull_request:
-    paths:
-      - "**/*.md" # Verified: files exist
-      - "**/*.json" # Verified: files exist
-```
-
-### Use Consistent Pattern Syntax
-
-```yaml
-# Preferred: Double-star for recursive matching
-- "**/*.md"
-- "**/*.json"
-```
-
-## Common Mistakes
-
-```yaml
-# Mistake 1: Assuming success when pattern matches nothing
-- run: git add --renormalize -- '*.markdown'  # Fails if no .markdown files
-
-# Mistake 2: Case sensitivity on Linux
-git ls-files '*.MD'   # Different from '*.md' on Linux
-
-# Mistake 3: Over-broad patterns (stages everything)
-- run: git add --renormalize .  # Use per-extension loop instead
-```
-
-## Integration with Workflow Consistency
-
-This skill complements the [Workflow Consistency skill](./workflow-consistency.md) by
-ensuring pattern validation for renormalize commands and path trigger synchronization.
-
-## Validation Checklist
-
-- [ ] Uses per-extension loop pattern with existence checks (REQUIRED)
-- [ ] All path patterns match at least one file
-- [ ] Patterns consistent between `pull_request` and `pull_request_target`
-- [ ] No patterns for dotfile-only extensions (e.g., `yaml`)
-
-## Verification
-
-Test patterns locally before committing:
-
-```bash
-# Verify file types exist
-for ext in cs md json asmdef yml; do
-  count=$(git ls-files "*.$ext" "**/*.$ext" | wc -l)
-  echo "$ext: $count files"
-done
-```
-
-Run automated validation:
-
-```bash
-node scripts/validate-workflows.js
-```
-
-This validation runs in CI (via actionlint workflow) but not in pre-commit hooks.
-
-## See Also
-
-- [Workflow Consistency skill](./workflow-consistency.md) - General workflow structure requirements
-- [Cross-Platform Compatibility skill](../scripting/cross-platform-compatibility.md) - Path handling across OSes
-- [Git Workflow Robustness skill](../testing/git-workflow-robustness.md) - Git operations in CI