session-distill

Session Distill

Convert a working session into an artifact that survives the session. The artifact is written by hand or by the manual helper; nothing is captured automatically.

When to Use

End of a work session
Before a context compaction
Handing work to another agent or person
After a long debugging session
Weekly, to consolidate several sessions

Procedure

Artifact

Save to plans/sessions/YYYY-MM-DD-<short-name>.md. The private plans/ tree is gitignored and excluded from catalog, install, and package discovery.

Required sections:

# Session: YYYY-MM-DD - <short name>

## What we did
- [Concrete change]

## Decisions made
- **Decision**: [what we chose] because [evidence]

## Files changed
- `path/to/file` - [one-line description]

## Open questions
- [Question deferred]

## Patterns observed
- [Reusable insight or anti-pattern]

## Next session
- [Concrete next action and owner]

Writing each section

What we did

Bullets, one concrete change each. Drop anything you cannot state concretely.

Decisions made

Use **Decision**: ... because .... The reason is the part a future session needs; a decision without a reason cannot be revisited.

Files changed

Include paths and one-line descriptions. This is the audit trail.

Open questions

Questions you did not answer. They move to the next session's artifact.

Patterns observed

The reusable section:

For a reusable pattern, draft under plans/skills/drafts/ using

knowledge-extract.

For a repeated mistake, add it to plans/anti-patterns.md.

Next session

Specific enough to act on. Name the file, function, or open question.

Optional helper

hooks/session-end.sh is a manual helper, not a registered hook. By default it stores no transcript and calls no model. Two explicit opt-ins change that:

AGENT_FOUNDRY_SESSION_PERSIST=1 appends a redacted raw transcript.
AGENT_FOUNDRY_SESSION_DISTILL=1 requests model distillation from the local

daemon and falls back to a labeled manual placeholder when unavailable.

Review the artifact before sharing. Redaction is pattern-based, not a guarantee.

Anti-patterns

A decision list with no reasons.
Recording only what changed, not what was checked.
Writing patterns directly into skills/ without review.
Pasting a raw transcript by default.
Treating a model-distilled summary as a record of fact.

References

details

Verification Checklist

[ ] All six sections are present.
[ ] Every decision includes a reason.
[ ] Changed files have paths and descriptions.
[ ] Patterns point to a draft path under plans/.
[ ] No transcript is stored unless the persist opt-in was set.

Install and discovery

Contents