import live www.sillylaird.ca webrootHEADmain

1 files changed, 518 insertions, 0 deletions

diff --git a/.agents/skills/skill-improver/references/plan-format.md b/.agents/skills/skill-improver/references/plan-format.md
new file mode 100644
index 0000000..ab6e6df
--- /dev/null
+++ b/.agents/skills/skill-improver/references/plan-format.md
@@ -0,0 +1,518 @@
+# Improvement Plan Format
+
+Detailed specification of the `improvement-plan-{skill-name}.md` file format generated by `skill-quality-reviewer` and consumed by `skill-improver`.
+
+## File Structure
+
+```markdown
+# Skill Improvement Plan: {skill-name}
+
+## Priority Summary
+- **High Priority**: {count} items
+- **Medium Priority**: {count} items
+- **Low Priority**: {count} items
+
+## High Priority Improvements
+
+### 1. [Issue Title]
+**File**: SKILL.md:line:line
+**Dimension**: {Dimension Name}
+**Impact**: +X points
+
+**Current**:
+```yaml or markdown
+{current content}
+```
+
+**Suggested**:
+```yaml or markdown
+{suggested content}
+```
+
+**Reason**: {why this improves quality}
+
+[Repeat for all high priority items...]
+
+## Medium Priority Improvements
+[Same format as High Priority...]
+
+## Low Priority Improvements
+[Same format as High Priority...]
+
+## Quick Wins (Easy Fixes)
+1. {quick fix description}
+2. {quick fix description}
+
+## Estimated Time to Complete
+- High Priority: X hours
+- Medium Priority: X hours
+- Low Priority: X hours
+- **Total**: X hours
+
+## Expected Score Improvement
+- Current: X/100 ({Grade})
+- After High Priority: X/100 ({Grade})
+- After All: X/100 ({Grade})
+```
+
+## Parsing Rules
+
+### Priority Section Detection
+
+**Identify sections by heading:**
+```markdown
+## High Priority Improvements
+## Medium Priority Improvements
+## Low Priority Improvements
+```
+
+**Case insensitive but exact match preferred:**
+- "High Priority Improvements" ✓
+- "high priority improvements" ✓ (acceptable)
+- "High Priority" ✗ (incomplete)
+
+### Item Extraction
+
+**Each improvement item starts with:**
+```markdown
+### N. [Issue Title]
+```
+
+Where N is a sequential number (1, 2, 3, ...)
+
+**Required fields within each item:**
+
+1. **File** (required)
+   ```
+   **File**: SKILL.md:line:line
+   **File**: references/filename.md
+   **File**: examples/filename.md
+   ```
+   - Format: `filepath:line:line` or just `filepath`
+   - Line numbers are specific for edits
+   - File only indicates new file creation or append
+
+2. **Dimension** (required)
+   ```
+   **Dimension**: Description Quality
+   **Dimension**: Content Organization
+   **Dimension**: Writing Style
+   **Dimension**: Structural Integrity
+   ```
+
+3. **Impact** (required)
+   ```
+   **Impact**: +X points
+   ```
+   - Points indicate expected score improvement
+   - Used for calculating expected final score
+
+4. **Current** (required for edits)
+   ```
+   **Current**:
+   ```yaml or markdown
+   {exact current content}
+   ```
+   - Must match exactly for Edit operations
+   - Code fence specifies format (yaml, markdown, etc.)
+
+5. **Suggested** (required)
+   ```
+   **Suggested**:
+   ```yaml or markdown
+   {suggested replacement content}
+   ```
+   - Content to replace current or create
+
+6. **Reason** (optional but recommended)
+   ```
+   **Reason**: {explanation}
+   ```
+   - Human-readable explanation
+   - Included in update report
+
+### Code Fence Formats
+
+**Supported formats:**
+```yaml
+```yaml
+---
+name: skill-name
+---
+```
+```
+
+```markdown
+```markdown
+## Section Header
+
+Content here...
+```
+```
+
+```bash
+```bash
+#!/bin/bash
+echo "script"
+```
+```
+
+**Format determines:**
+- Syntax highlighting
+- Validation rules
+- Parser expectations
+
+## File Path Patterns
+
+### SKILL.md References
+
+**With line numbers:**
+```
+**File**: SKILL.md:5:10
+```
+- Lines 5-10 will be replaced
+- Used for Edit operations
+
+**Without line numbers:**
+```
+**File**: SKILL.md
+```
+- Typically indicates new file or append
+
+### References/ Files
+
+**Specific file:**
+```
+**File**: references/api-guide.md
+**File**: references/examples-bad.md
+```
+
+**With line numbers:**
+```
+**File**: references/patterns.md:50:100
+```
+
+### Examples/ Files
+
+**New file creation:**
+```
+**File**: examples/demo.md
+```
+- No line numbers
+- Suggested content becomes entire file
+
+**Modification:**
+```
+**File**: examples/basic-usage.sh:20:30
+```
+
+### Scripts/ Files
+
+**Script updates:**
+```
+**File**: scripts/validate.sh:15:25
+```
+
+## Parsing Pseudocode
+
+```python
+def parse_improvement_plan(plan_path):
+    """Parse improvement plan file into structured data."""
+
+    plan = read_file(plan_path)
+    sections = {
+        'high': [],
+        'medium': [],
+        'low': []
+    }
+
+    current_section = None
+    current_item = None
+
+    for line in plan.split('\n'):
+        # Detect section headers
+        if line.startswith('## High Priority'):
+            current_section = 'high'
+        elif line.startswith('## Medium Priority'):
+            current_section = 'medium'
+        elif line.startswith('## Low Priority'):
+            current_section = 'low'
+
+        # Detect item start
+        elif line.startswith('### '):
+            if current_item:
+                sections[current_section].append(current_item)
+            current_item = {'title': line[4:].strip()}
+
+        # Parse fields within item
+        elif current_item:
+            if line.startswith('**File**'):
+                current_item['file'] = parse_file_path(line)
+            elif line.startswith('**Dimension**'):
+                current_item['dimension'] = line.split(':', 1)[1].strip()
+            elif line.startswith('**Impact**'):
+                current_item['impact'] = parse_impact(line)
+            elif line.startswith('**Current**'):
+                current_item['current'] = extract_code_fence(plan, line)
+            elif line.startswith('**Suggested**'):
+                current_item['suggested'] = extract_code_fence(plan, line)
+            elif line.startswith('**Reason**'):
+                current_item['reason'] = line.split(':', 1)[1].strip()
+
+    # Add last item
+    if current_item:
+        sections[current_section].append(current_item)
+
+    return sections
+```
+
+## Line Number Handling
+
+### Single Line
+
+```
+**File**: SKILL.md:10:10
+```
+- Only line 10 is replaced
+
+### Line Range
+
+```
+**File**: SKILL.md:10:15
+```
+- Lines 10-15 are replaced
+- Current content should span these lines
+
+### No Line Numbers
+
+```
+**File**: references/new-file.md
+```
+- New file creation
+- Or append to existing file
+
+### Line Number Extraction
+
+```python
+def parse_file_path(line):
+    """Extract file path and line numbers from File field."""
+
+    # Remove "**File**:" prefix
+    value = line.split(':', 1)[1].strip()
+
+    # Check for line numbers
+    if ':' in value:
+        parts = value.split(':')
+        file_path = ':'.join(parts[:-2])
+        start_line = int(parts[-2])
+        end_line = int(parts[-1])
+        return {
+            'path': file_path,
+            'start': start_line,
+            'end': end_line
+        }
+    else:
+        return {
+            'path': value,
+            'start': None,
+            'end': None
+        }
+```
+
+## Impact Extraction
+
+```python
+def parse_impact(line):
+    """Extract impact value from Impact field."""
+
+    # Format: **Impact**: +X points
+    value = line.split(':', 1)[1].strip()
+    # Extract number
+    import re
+    match = re.search(r'\+(\d+)', value)
+    if match:
+        return int(match.group(1))
+    return 0
+```
+
+## Code Fence Extraction
+
+```python
+def extract_code_fence(content, start_line):
+    """Extract code block starting after current line."""
+
+    lines = content.split('\n')
+    start_idx = lines.index(start_line)
+
+    # Find opening fence
+    for i in range(start_idx, len(lines)):
+        if lines[i].strip().startswith('```'):
+            fence_start = i
+            lang = lines[i].strip()[3:]
+            break
+
+    # Find closing fence
+    for i in range(fence_start + 1, len(lines)):
+        if lines[i].strip() == '```':
+            fence_end = i
+            break
+
+    # Extract content
+    code_lines = lines[fence_start + 1:fence_end]
+    return '\n'.join(code_lines)
+```
+
+## Validation Rules
+
+### Required Sections
+
+- [ ] High Priority Improvements (may be empty)
+- [ ] Medium Priority Improvements (may be empty)
+- [ ] Low Priority Improvements (may be empty)
+
+### Required Item Fields
+
+For each improvement item:
+- [ ] **File** field present
+- [ ] **Dimension** field present
+- [ ] **Impact** field present
+- [ ] **Current** field present (for edits)
+- [ ] **Suggested** field present
+
+### File Path Validity
+
+- [ ] File path is valid format
+- [ ] Line numbers are integers (if present)
+- [ ] File extension matches content type
+
+### Code Fence Validity
+
+- [ ] Opening fence present
+- [ ] Closing fence present
+- [ ] Language identifier valid
+- [ ] Content non-empty (for suggested)
+
+## Example Improvement Plan
+
+```markdown
+# Skill Improvement Plan: example-skill
+
+## Priority Summary
+- **High Priority**: 2 items
+- **Medium Priority**: 1 item
+- **Low Priority**: 1 item
+
+## High Priority Improvements
+
+### 1. Fix Description Trigger Phrases
+**File**: SKILL.md:3:5
+**Dimension**: Description Quality
+**Impact**: +20 points
+
+**Current**:
+```yaml
+---
+name: example-skill
+description: Use this for helpful tasks.
+---
+```
+
+**Suggested**:
+```yaml
+---
+name: example-skill
+description: This skill should be used when the user asks to "validate data",
+"check schemas", or "verify formats". Perform data validation and schema
+checking for JSON and YAML files.
+---
+```
+
+**Reason**: Add specific trigger phrases and use third-person format.
+
+### 2. Fix Writing Style
+**File**: SKILL.md:25:30
+**Dimension**: Writing Style
+**Impact**: +15 points
+
+**Current**:
+```markdown
+## Overview
+You should use this skill to validate data files. You can choose from
+JSON or XML formats.
+```
+
+**Suggested**:
+```markdown
+## Overview
+Validate data files in JSON or XML formats with configurable schemas.
+```
+
+**Reason**: Change to imperative form, remove second person.
+
+## Medium Priority Improvements
+
+### 1. Add Reference Documentation
+**File**: references/validation-rules.md
+**Dimension**: Content Organization
+**Impact**: +10 points
+
+**Suggested**:
+```markdown
+# Validation Rules
+
+## JSON Schema Rules
+- Required fields validation
+- Type checking
+- Format validation
+
+## YAML Schema Rules
+- Structure validation
+- Type coercion rules
+```
+
+**Reason**: Move detailed rules to references for progressive disclosure.
+
+## Low Priority Improvements
+
+### 1. Clarify Description
+**File**: SKILL.md:50:52
+**Dimension**: Writing Style
+**Impact**: +5 points
+
+**Current**:
+```markdown
+## Usage
+Use the skill when you need to validate files.
+```
+
+**Suggested**:
+```markdown
+## Usage
+Invoke skill for file validation tasks.
+```
+
+**Reason**: Use imperative form for consistency.
+
+## Quick Wins (Easy Fixes)
+1. Add space after comma in description (+2 points)
+2. Fix indentation in examples section (+3 points)
+
+## Estimated Time to Complete
+- High Priority: 0.5 hours
+- Medium Priority: 0.5 hours
+- Low Priority: 0.25 hours
+- **Total**: 1.25 hours
+
+## Expected Score Improvement
+- Current: 65/100 (D)
+- After High Priority: 82/100 (B-)
+- After All: 88/100 (B+)
+```
+
+## Integration Notes
+
+**Generated by:** `skill-quality-reviewer`
+**Consumed by:** `skill-improver`
+
+**Format version:** 1.0
+**Compatibility:** Must maintain backward compatibility