Inspect amend

Inspect & Amend — Self-Improving Skills Loop

Trigger

• "Inspect skills", "Check skill health", "Review skill performance"
• "Amend {skill_name}", "Improve {skill_name}"
• "Calibrate skills" — run inspection across all skills
• Automatically suggested when _logs/_flags.md has 3+ entries for the same skill

Purpose

Close the self-improvement loop: observe → inspect → amend → evaluate. Content generation skills degrade when platforms change algorithms, voice drifts, Brain data grows stale, or audience preferences shift. This skill detects degradation and proposes evidence-based amendments.

Process

Phase 1 — Inspect

1. Read all observation logs from _logs/ for the target skill

2. Read _logs/_flags.md for flagged issues

3. Identify patterns:

   • Rubber Duck failures: Which phases consistently score low? (e.g., CHALLENGE always fails = weak counterarguments)
   • Format drift: A format that used to pass now consistently fails
   • Angle bias: System always picks the same angle (contrarian overuse)
   • Expert mismatch: Wrong expert library loaded for task type
   • Decontamination noise: Same banned patterns keep triggering (instruction unclear)
   • Brain staleness: Research skill finds data already in Brain, or Brain data contradicts current reality
   • Revision loops: Too many rounds needed — instructions may be ambiguous

4. Generate an Inspection Report:

## Inspection Report: {skill_name}
**Date**: {YYYY-MM-DD}
**Observation window**: {date range}
**Total runs observed**: {N}
**Pass rate (Rubber Duck 8+)**: {N}%
**Avg revision rounds**: {N}

### Patterns Detected
1. {Pattern with evidence — cite specific log entries}
2. {Pattern with evidence}

### Root Cause Analysis
- Is the issue in the skill instructions?
- Is it in the reference files (practices, expert libraries)?
- Is it in the Brain data (stale models, missing evidence)?
- Is it in the routing (wrong skill triggered)?

### Recommendation
{Amend skill | Update reference | Refresh Brain section | Adjust routing | Monitor}

Phase 2 — Amend

If inspection recommends amendment:

1. Read the current SKILL.md for the target skill

2. Propose a specific change — one of:

   • Tighten angle selection criteria
   • Add missing generation step
   • Update format constraints (character counts, structure)
   • Adjust Rubber Duck phase weights or criteria
   • Update expert library loading rules
   • Add/remove decontamination patterns
   • Clarify ambiguous instructions causing revision loops
   • Update Brain loading priorities

3. Version the current skill before changing:

   • Create skills/{skill_name}/_versions/ if it doesn't exist
   • Copy current SKILL.md → _versions/v{N}.md
   • Write amendment rationale to _versions/_changelog.md:

     ## v{N+1} — {YYYY-MM-DD}
     **Trigger**: {What pattern triggered this amendment}
     **Change**: {What was changed and why}
     **Evidence**: {Log entries that support this change}
     **Expected improvement**: {What metric should improve}
     

4. Present the proposed diff to the user for approval

   • Show exact lines changed
   • Explain the evidence chain: logs → pattern → root cause → fix
   • Never apply without user confirmation

Phase 3 — Evaluate

After amendment is applied:

1. Mark in _logs/_flags.md:

   - [EVAL] {skill_name} v{N+1} applied {date} — monitoring
   

2. After 3-5 subsequent runs, compare:

   • Rubber Duck pass rate before vs. after
   • Avg revision rounds before vs. after
   • Phase-specific scores before vs. after
   • Decontamination trigger frequency

3. Generate Evaluation Report:

   ## Evaluation: {skill_name} v{N+1}
   **Amendment date**: {date}
   **Runs since**: {N}
   **Result**: Improved | No change | Degraded
   
   ### Metrics Comparison
   | Metric | Before | After |
   |--------|--------|-------|
   | Pass rate | {x}% | {x}% |
   | Avg revisions | {x} | {x} |
   | Weakest phase | {x} | {x} |
   
   ### Decision
   {Keep | Roll back to v{N}}
   

4. If degraded: restore from _versions/v{N}.md, log the rollback

Amendment Thresholds

• Trigger threshold: Only propose amendment when Rubber Duck first-attempt pass rate drops below 50% over 10+ runs, OR when 3+ flags accumulate for the same skill
• Improvement bar: An amendment must improve the pass rate by at least 15 percentage points OR reduce average revision rounds by at least 1 round
• Revert rule: If an amended skill doesn't improve the primary metric within 5 subsequent runs, auto-revert. No exceptions.
• Cooldown: After a revert, wait for 3 clean runs before proposing a new amendment to the same skill

Rules

• Never amend without inspection evidence
• Never apply without user approval
• Always version before amending
• One amendment per cycle — don't stack changes
• Evaluate before proposing next amendment
• Smallest change that addresses the pattern
• If root cause is in references (not skill), update the reference file instead