path: root/.agents/skills/skill-improver/references/plan-format.md

# 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