com.wallstop-studios.dxmessaging 2.1.4 → 2.1.6

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/github-actions/git-renormalize-patterns.md

@@ -0,0 +1,231 @@
+---
+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