kss explainer · 02 · self-improvement loop

How a skill fixes itself.

Most agent frameworks ship rigid skills. When one misfires, you have nowhere to put the feedback, so the same friction recurs forever. kss closes the loop — when a skill misfires, you log a short report; after enough reports accumulate, skill-autopsy proposes a concrete diff against that skill's SKILL.md.

Click slots on the timeline below. Watch what changes at the 4-report and 6-report thresholds. Flip the ~/.kss-source toggle to see how the outcome path differs for forkers vs. plain installs.

Why this design?
"Your frustration is the input."
create autopsy report /kss:skill-autopsy save reports saved per skill ~/kss-skill-reports/ at 4+ autopsy consolidate analyze · propose diff apply SKILL.md improves diff applied ✓ next iteration — the skill is now sharper

The threshold (4 reports) is deliberate. One report is an incident; two is a coincidence; four is a pattern.

Report timeline  ·  click a slot to set count
consolidate offered at 4 reports escalation at 6 reports 1 2 3 4 5 6 7 8 ~/kss-skill-reports/<skill>.md → time
logging consolidate offered  (4+) escalation  (6+)
Logging mode Consolidate offered Escalation
If you run /kss:skill-autopsy <skill> now
If you accept consolidation

The full flow, top to bottom.

For when the interactive isn't enough. This is the canonical sequence.

1
A skill misfires during real work.

You ran /kss:capture, but it asked you for a trigger condition you didn't have on hand. Or /kss:plan-milestone over-scoped the chunk. The friction is fresh — capture it now or lose it.

2
/kss:skill-autopsy <skill-name>

Autopsy interviews you in 3-5 questions. Writes a short report at ~/kss-skill-reports/<skill>.md. The path is intentional — these are personal and never committed to the plugin source.

3
Reports accumulate as you use the skill.

At 4+ reports for the same skill, autopsy offers to consolidate. Past 5, the warning escalates — defer at your peril, because the same friction will keep recurring.

4
/kss:skill-autopsy <skill> --consolidate

Reads all reports for that skill. Looks for recurring root causes, not surface symptoms. If reports are vague or share no pattern, says so honestly instead of inventing improvements. Otherwise: proposes a concrete diff against the skill's SKILL.md.

5
The fork: source-set vs. source-not-set.

If ~/.kss-source points to your clone: diff is applied to your local SKILL.md. Reports for that skill are cleared. You review, commit, push (or open a PR) on your own time.

Otherwise: diff is printed for you to handle manually — fork later to apply, open a GitHub issue to send upstream, or just adapt your usage. Reports can be cleared either way.