Remediation Planning Guide

Guide for creating remediation plans from skill quality audit results.

When to Use This Guide

Use this guide when:

• A skill has been audited and scored below target (typically <108/120, grade B or lower)
• You need to create an actionable plan to improve skill quality
• Converting audit findings into structured improvement tasks

Prerequisites

1. Completed Audit: Run skill-auditor evaluate <skill-name> --json
2. Audit Report: Location should be .context/audits/<skill-name>-audit-YYYY-MM-DD.md
3. Template: Load templates/remediation-plan-template.yaml

Standard Remediation Plan Format

All remediation plans follow this structure:

Executive Summary

Focus Areas: Top 2-3 dimensions requiring attention

Verdict: One-line summary: "Priority improvements required" vs "Targeted improvements recommended"

Critical Issues Table

Identify the top 3-5 issues from the audit:

Prioritize by:

1. Critical/High severity
2. Dimensions with lowest scores
3. Issues blocking other improvements

Detailed Remediation Steps

For each priority dimension:

### Phase N: [Dimension Name] - Priority: [Priority]

**Target**: Increase from [current]/[max] to [target]/[max] (+[delta] points)

#### Step N.1: [Specific Action]

**[File to modify]**: `path/to/file.md`

[Code example if applicable]

Code Block Escaping

When documenting code examples that contain markdown code fences, use 4 backticks:

**BAD**:
```markdown
Some markdown content here
```

**GOOD**:
```markdown
Good content here
```

Success Criteria

Measurable targets for verification:

Effort Estimate

Additional Sections

• Dependencies: Any prerequisites or blockers
• Rollback Plan: Git command to revert changes
• Notes: Honest assessment of plan quality (rating out of 10)

Honest Rating Guidelines

Rate plans based on:

Common Remediation Patterns

Pattern 1: Anti-Pattern Addition

For D3 (Anti-Pattern Quality) improvements:

## Anti-Patterns

### NEVER: [Action]

**WHY**: [Reason]

**BAD**:
```[language]
[bad code]
```

**GOOD**:
```[language]
[good code]
```

Pattern 2: Reference Creation

For D5 (Progressive Disclosure) improvements:

1. Create skills/<skill>/references/ directory
2. Extract detailed content from SKILL.md
3. Add navigation table to SKILL.md:

## Quick Reference

| Topic | Reference |
|-------|-----------|
| Topic Name | [references/topic.md](references/topic.md) |

Pattern 3: Trigger Expansion

For D7 (Pattern Recognition) improvements:

Update frontmatter description:

---
name: skill-name
description: |
  [Core description]. Use when: [trigger phrases].
  
  Keywords: [comma-separated keywords]
---

Verification

After implementing remediation:

skill-auditor evaluate <skill-name> --json
bunx markdownlint-cli2 "skills/<skill-name>/**/*.md"

Compare new score against target in plan.

Related References

• framework-dimensions.md - Understanding the 8 dimensions
• framework-scoring-rubric.md - How scores are calculated
• aggregation-pattern.md - For larger consolidation efforts