adaptationio/improvement-workflow

Improvement Workflow

Overview

improvement-workflow orchestrates the complete continuous improvement cycle for Claude Code skills, transforming review findings into applied improvements and validated enhancements.

Purpose: End-to-end skill improvement from review through validated enhancement

Component Skills (5):

1. review-multi - Comprehensive multi-dimensional review (identify issues)
2. analysis - Pattern analysis across findings (understand systemic issues)
3. best-practices-learner - Extract learnings (capture insights)
4. skill-updater - Apply improvements (implement changes)
5. skill-validator - Validate improvements (ensure quality maintained)

Workflow Pattern: Sequential pipeline with feedback loop

Result: Systematically improved skills with validated enhancements and captured learnings

When to Use

• Continuous improvement iterations (make good skills better)
• Applying review recommendations (systematic implementation)
• Post-deployment enhancement (v1.0 → v1.1)
• Multiple skill improvements (consistent process)
• Learning-driven development (capture and apply insights)

Improvement Workflow

Step 1: Comprehensive Review (review-multi)

Purpose: Identify improvement opportunities through multi-dimensional assessment

Process: Run review-multi comprehensive mode (all 5 operations)

Outputs:

• Overall score and grade
• Per-dimension scores
• Prioritized improvement recommendations
• Identified issues and anti-patterns

Time: 1.5-2.5 hours

---

Step 2: Pattern Analysis (analysis)

Purpose: Understand systemic patterns in findings

Process: Use analysis Operation 5 (Pattern Recognition)

• Review findings from Step 1
• Identify recurring themes (if reviewing multiple skills)
• Understand root causes
• Prioritize by impact

Outputs:

• Pattern analysis (systemic issues vs one-offs)
• Root cause understanding
• Impact-prioritized improvements

Time: 45-90 minutes

---

Step 3: Extract Learnings (best-practices-learner)

Purpose: Capture insights for future application

Process: Use best-practices-learner Operations 1-2

• Extract patterns from review findings
• Document what worked/didn't work
• Capture insights for guidelines

Outputs:

• Documented patterns
• Learnings log
• Insights for guideline updates

Time: 30-60 minutes

---

Step 4: Apply Improvements (skill-updater)

Purpose: Systematically implement improvements

Process: Use skill-updater workflow

1. Plan updates (prioritize recommendations)
2. Backup skill
3. Apply changes (one at a time)
4. Test each change

Outputs:

• Updated skill with improvements applied
• Change documentation
• Version update

Time: 1-4 hours (varies by number of improvements)

---

Step 5: Validate Improvements (skill-validator + review-multi)

Purpose: Ensure improvements effective, no regressions

Process:

1. Run skill-validator (ensure still passes minimum standards)
2. Re-run review-multi (compare before/after scores)
3. Validate improvements achieved goals
4. Document impact

Outputs:

• Validation results (pass/fail)
• Before/after score comparison
• Impact measurement
• Regression check

Time: 30-60 minutes

---

Step 6: Update Guidelines (best-practices-learner)

Purpose: Feed learnings back into ecosystem

Process: Use best-practices-learner Operation 3

• Update common-patterns.md with new patterns
• Update templates if needed
• Propagate learnings to future skills

Outputs:

• Updated guidelines
• Improved templates
• Enhanced ecosystem knowledge

Time: 20-40 minutes

---

Post-Workflow: Iteration Decision

After completing workflow:

If Score Improved Significantly (≥0.5 points):

• ✅ Improvements effective
• Document success
• Apply similar improvements to other skills

If Score Improved Slightly (<0.5 points):

• ⚠️ Minor impact
• Assess if effort worth benefit
• Consider different improvements

If Score Unchanged or Decreased:

• ❌ Improvements ineffective or caused regressions
• Review what went wrong
• Revert changes if regression
• Try different approach

Iterate:

• Can run workflow again for further improvements
• Diminishing returns after 2-3 iterations
• Focus on highest-impact improvements first

---

Best Practices

1. Review Before Improve

Practice: Always review comprehensively before changing

Rationale: Understand current state fully prevents fixing wrong things

2. Prioritize by Impact

Practice: Apply high-impact improvements first

Rationale: Maximum benefit for effort invested

3. One Improvement at a Time

Practice: Apply and validate each change individually

Rationale: Prevents compounding errors, identifies what actually helped

4. Measure Impact

Practice: Compare before/after scores objectively

Rationale: Data-driven understanding of effectiveness

5. Capture Learnings

Practice: Document what worked for future application

Rationale: Learnings compound across improvements

---

Quick Reference

The 6-Step Improvement Workflow

| Step | Skill | Purpose | Time | Output | |------|-------|---------|------|--------| | 1 | review-multi | Comprehensive review | 1.5-2.5h | Scores, recommendations | | 2 | analysis | Pattern analysis | 45-90m | Systemic insights | | 3 | best-practices-learner | Extract learnings | 30-60m | Documented patterns | | 4 | skill-updater | Apply improvements | 1-4h | Updated skill | | 5 | skill-validator + review-multi | Validate improvements | 30-60m | Impact measurement | | 6 | best-practices-learner | Update guidelines | 20-40m | Enhanced ecosystem |

Total Time: 5-9 hours for complete improvement cycle

Workflow Pattern

review-multi → Identify improvements
    ↓
analysis → Understand patterns
    ↓
best-practices-learner → Extract learnings
    ↓
skill-updater → Apply changes
    ↓
validate → Measure impact
    ↓
Update guidelines → Feed ecosystem

Typical Improvements

• Add Quick Reference (UX)
• Enhance examples (clarity)
• Refine validation criteria (specificity)
• Add error handling (completeness)
• Improve integration docs (workflow skills)

---

improvement-workflow enables systematic, validated, learning-driven skill enhancement with ecosystem-wide knowledge propagation.