/distill

name: distill
description: When there's a failure, bug, unexpected behavior, or important finding, distills it into a verified general rule saved under .loop/memory/. Invoke right after resolving a gate (test/typecheck) failure, right after fixing a verifier-graded fail, or right after pinning down a cause through debugging. Exclude failures with no lesson, e.g. a plain typo fix.
argument-hint: "[one-line summary of the failure/finding]"

Distill — distill a failure into verified knowledge

Do the 5 stages in order. Don't skip any.

1. Fail — record in the ledger

Add a row to the `.loop/memory/LEDGER.md` table: `| YYYY-MM-DD | <symptom one-liner> | fail | |`

2. Investigate — find the cause

Find the cause, not the symptom. Check the relevant code/logs/commits and form a hypothesis.

3. Verify — pin the diagnosis down as fact

Verify the hypothesis by reproduction or refutation (reproduce the failure → apply the fix → confirm it passes is best). On success, set the LEDGER stage to `verify`. If you can't verify, record the note with `verified: false` and state in the body that it's a "hypothesis".

4. Distill — abstract into a general rule

• **Prefer updating an existing note over creating a new one.** Look for a related note in `notes/` first

(INDEX category + grep), and if there is one, update it.

• A new note is `notes/<kebab-slug>.md`:

---
title: "<the general rule as a sentence>"
tags: [<domain tags>]
category: debugging   # debugging | pattern | environment | decision
confidence: high      # high | medium | low
verified: true        # whether it passed stage 3
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: ["commit:<sha>", "session:<date-id>"]
---
<Describe the environment-specific fact and the general rule separately.
Not "in this project it was X" but "under condition C, Y happens. This project's case: X">
Related: [[other-note-slug]]

• Add a `[[this note slug]]` backlink to the related existing note. Broken links are allowed

(a marker for knowledge to be written later).

• Add a line to the matching category in `INDEX.md`, and update the top stats (note count · verified ratio ·

update date).

• The matching LEDGER row: set the stage to `distilled`, and put `[[slug]]` in the note column.

5. Consult — confirm reachability

Confirm the note you wrote is reachable from INDEX (present in the category table of contents). The next session learns this note exists via SessionStart injection.