Distill Knowledge

distill-knowledge

This is the only workflow phase that may make semantic updates to tracked AGENTS.md.

review-agents-tree may auto-apply only trivial non-semantic hygiene fixes.

It must never write AGENTS.override.md.

This skill must run from a fresh context window. If the current context contains implementation/review backstory beyond what a fresh distiller should rely on, stop and restart before curating durable context.

Run it after implementation and both code-review phases are clean enough to freeze the task outcome.

Read first

• ../references/task-packet-contract.md
• ../references/persistent-artifacts-contract.md
• ../references/review-phases-contract.md
• ../references/final-state-authoring-policy.md
• ../references/initiative-workflow-contract.md when distilling an initiative outcome
• ../../references/communication-mode.md
• relevant tracked AGENTS.md chain
• current task packet
• final relevant code and tests for any candidate under consideration
• final diff

If AGENTS.override.md exists locally, do not rely on it for canonical repository semantics.

Distill workflow

1. Read the packet and final code/tests for durable residue only.

• Focus on PLAN.md, review files, AMENDMENTS.md, ARTIFACT_CANDIDATES.md, the final relevant code/tests, and the final diff.
• Verify candidates against the current code/tests, not just the diff hunks.
• Ignore implementation chatter that does not survive contact with the final code.

1. Triage candidates.

• Promote only candidates that are:
• not recoverable reliably from code/tests
• durable beyond the current task
• costly to forget
• not better encoded in code, names, or tests
• Prefer no-op over weak prose.

1. Choose the right landing zone.

• Use the nearest stable tracked AGENTS.md owner boundary.
• Prefer the deepest correct tracked shard for one clear owner, but stop at the smallest stable common owner when the residue spans a broader module or several sibling owners.
• In cross-repo initiative work, durable landing follows residue ownership, not automatically the parent initiative repo.
• Do not create a new tracked shard without explicit human approval.

1. Choose the right section.

• Every tracked AGENTS.md needs ## Scope.
• Keep ## Scope lean and non-tautological: owner / applies-to / boundary clarification only. Do not merely restate the current directory path or obvious folder ownership.
• ## Commands & Validation for durable run/build/test/lint commands, first validation, or done when checks.
• ## Entrypoints only for root or hub-level start-here navigation that materially reduces search time. Deep leaf shards should usually omit it.
• Avoid raw file-path links by default; prefer stable owner/module names or task-class wayfinding.
• ## Constraints for hard do/don't rules, invariants, or externally imposed constraints.
• ## Decisions & Gotchas for non-obvious rationale, tempting rejected paths, revisit triggers, or traps.

1. Handle drift explicitly.

• If tracked AGENTS.md conflicts with code/tests, trust code/tests.
• Propose update, supersede, or removal instead of preserving stale guidance.

1. Apply the approval rule.

• Trivial navigation/hygiene updates may be applied directly.
• Semantic add/supersede/delete requires explicit human approval before writing.
• Sharding, scope changes, or meaning-changing conflict resolution requires explicit human approval.

1. Prune aggressively.

• Append-only is forbidden.
• Remove or supersede stale guidance when code/tests now encode it better.

1. Update INDEX.md with a short distill outcome note.

• If the packet has no further implementation or review work after distill, it may be marked done.

1. Commit before reporting back when distill changed the workspace.

• If you updated tracked AGENTS.md, packet artifacts, or other repo files, make a focused git commit before reporting to the lead.
• Use a Conventional Commit message matching the actual distill change.
• Include the commit hash and subject in the handoff.
• If the correct distill result is no_op, do not create a dummy commit.

Selection heuristics

Promote decisions when the future agent needs to know:

• why a strange choice is intentional
• which rejected path should not be resurrected casually
• what hidden external constraint shaped the code
• what revisit trigger would make the decision worth reopening

Promote entrypoints when the future agent would otherwise waste time rediscovering:

• where a recurring class of change starts
• which owner/module defines the behavior
• which first validation command gives fast confidence

Promote commands/validation when the future agent would otherwise guess:

• how to run the area safely
• which command gives the fastest useful signal
• what done means for recurring work in this boundary

Commit-before-report rule

For distill work that changed the workspace:

• commit before reporting back to the requester
• include the commit hash and subject in the handoff
• prefer a focused commit over bundling unrelated residue edits together
• if the result is no_op, explicitly say no commit was needed

Requester-response rule

Always report the distill result back to the requesting side.

• If the lead/orchestrator requested the distill pass, reply back to the lead/orchestrator.
• If a human directly requested the distill pass in this pane, reply back in this pane.
• Local pane output without an explicit reply to the requester does not count as completion.

Output shape

Default distill outcome should say one of:

• no_op
• updated_tracked_root_agents
• updated_tracked_local_agents
• proposed_semantic_agents_update_pending_approval
• pruned_stale_agents_guidance

Do not

• summarize the implementation
• restate behavior already obvious from code/tests
• promote every candidate just because it exists
• use tracked AGENTS.md as a worklog or shadow spec
• write AGENTS.override.md

Initiative mode

When initiative mode is active:

• treat sync-initiative as the working-memory sync phase, not the durable distill phase
• read the parent initiative packet plus relevant child ARTIFACT_CANDIDATES.md
• read INDEX.md field Next durable distill: now | later
• default to no_op mid-initiative unless the field says now and the residue is already stable/reusable
• a child packet may live in an owner repo different from the parent initiative repo; durable distill should run in the repo that owns the residue
• cross-repo initiatives may require separate fresh-context distill passes in different owner repos
• at initiative close, run a final pass even if the correct durable result is still no_op
• after any non-final pass or explicit no-op, reset Next durable distill: later
• only the closeout pass that updates the parent initiative packet should write initiative Status: completed

Communication

Honor active caveman mode for user-facing replies per ../../references/communication-mode.md. Keep durable artifacts normal unless the human asks otherwise. Drop caveman for safety/clarity when needed, then resume.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: siarhei-belavus
• Source: siarhei-belavus/agent-public
• License: MIT

Install and usage instructions live in the source repository linked above.