learnings_skill

Overview

This skill captures and persists short, evidence-backed execution learnings into a machine-readable .learnings.jsonl file. It runs at natural delivery boundaries or on explicit cues and writes decision-shaping rules so future agents and contributors can reuse successful patterns and avoid footguns. The output is optimized for automated recall, deduplication, and later codification.

How this skill works

The skill inspects recent changes, validation signals, and command outputs (git status/diff, test results, logs) to gather concrete evidence. It distills candidate lessons into compact rules of the form "When X, prefer Y because Z", assigns an actionable snake_case status, and appends one JSON object per learning using a helper script that computes fingerprints and captures repo/branch context. It prefers 0–3 records per turn, defaults to review_later when evidence is thin, and never blocks the workflow.

When to use it

• At commit/PR/handoff boundaries to record decisions before shipping
• When a validation transition occurs (fail->pass, pass->fail, timeout->stable)
• After a strategy pivot or simplifying refactor
• On discovery of a footgun, brittle assumption, or recurring trap
• When a pattern repeatedly accelerates progress or debugging

Best practices

• Capture only lessons that will change future decisions—keep each learning actionable
• Ground every learning in observed evidence; include concrete commands, tests, or diffs
• Prefer concise statuses like do_more or do_less; use investigate_more/codify_now when needed
• Append immediately with the provided append script to avoid manual JSON edits
• Keep noise low: write nothing if no checkpoint occurred or evidence is absent

Example use cases

• After a flaky test turned green: append a learning with the failing test command and the fix that stabilized it
• When abandoning an approach: record a strategy pivot learning that explains why the new approach was chosen
• On discovering a recurring setup pitfall: add a footgun learning with reproduction steps and an avoidance rule
• Before opening a PR: run the skill to persist any last-minute delivery-boundary learnings
• When a quick pattern accelerates debugging: log a momentum discovery so others can reuse it