first commit
This commit is contained in:
@@ -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
|
||||
Reference in New Issue
Block a user