--- name: distill-best-practices description: > Cross-project best practices distillation. Reads changed memory files from all tracked projects and proposes additions, updates, or removals to ~/dev/claude/projects/best-practices/. Run from any project -- always targets skynet/best-practices repo as output. Interactive -- presents proposals for approval before making changes. allowed-tools: Read, Edit, Write, Glob, Grep, Bash(git -C *), Bash(git rev-parse *), Bash(ls *), Bash(cat *), Bash(head *), Bash(date *) --- # Distill Best Practices Skill You are extracting generalisable best practices from project-specific memory files across all tracked projects. ## Pre-gathered context ### Pre-gathered context (read at runtime) The following files should be read using the Read tool at the start of execution: - `~/dev/claude/projects/best-practices/.distill-state.json` — Distill state (if not found, treat as `{}`) - `~/dev/claude/projects/claude-foundations/settings.yaml` — Settings (if not found, use defaults from instructions) - `~/dev/claude/projects/best-practices/BESTPRACTICES.md` — Current best-practices index - Use Glob to list `~/dev/claude/projects/best-practices/*.md` for available topic files - Use Glob to list `~/dev/claude/projects/*/` for the projects directory listing ## Instructions ### Step 1: Discover changes per project The project root is `~/dev/claude` (hardcoded — change at the top of the `!`command`` blocks if your layout differs). Key paths: - **Settings**: `~/dev/claude/projects/claude-foundations/settings.yaml` - **Best practices dir**: `~/dev/claude/projects/best-practices/` - **Best practices index**: `~/dev/claude/projects/best-practices/BESTPRACTICES.md` - **Distill state**: `~/dev/claude/projects/best-practices/.distill-state.json` Read `settings.yaml` (pre-gathered above). For each project in `distill.projects`, get its path: `~/dev/claude//`. Also process any `distill.extra_projects` entries — these have a `path` field relative to `~/dev/claude`. For each project (from both lists): 1. Get current HEAD: `git -C rev-parse HEAD` 2. Look up `last_sha` from `.distill-state.json` for this project 3. If SHA matches → skip this project (no changes) 4. If `last_sha` exists → find changed files: `git -C diff --name-only ..HEAD -- memory/` 5. If `last_sha` is missing (first run) → list all memory files: `ls /memory/*.md` Filter to only `memory/*.md` files (exclude `memory/log/` — those are raw, unprocessed). If no projects have changes, say so and stop. ### Step 2: Read changed memory files For each changed memory file, read its full content using the Read tool. Also identify which existing best-practices topic files cover the same domain. Use this mapping as a guide: - `gotchas-k8s.md` → `kubernetes.md` - `gotchas-cilium.md` → `kubernetes.md` - `gotchas-helm.md` → `helm.md` - `gotchas-ansible.md` → `ansible.md` - `gotchas-sops.md` → `secrets-management.md` - `process-lessons.md` → `validation.md`, `debugging.md` - `decisions.md` → various (match by content) - Other gotchas → match by topic or propose a new file Read the matching best-practices files so you can compare. ### Step 3: Analyse and propose For each potential change, classify it: - **ADD**: A lesson that is project-agnostic and valuable across projects. When generalising: - Strip project-specific details (IPs, namespace names, service names, hostnames) - Replace specifics with generic descriptions (e.g., "10.111.0.5" → "the DNS server IP") - Keep the principle and the reasoning — lose the implementation detail - Only promote lessons that would apply to at least one other project type - **UPDATE**: An existing best-practice entry that has new supporting evidence, needs refinement, or should be expanded with a new example. - **REMOVE**: A best-practice that has been invalidated — version-specific bug fixed, tool changed, approach superseded. Cross-reference: if the source gotcha was removed from the project's memory, the best-practice may be stale. ### Step 4: Present proposals **Do NOT make any changes yet.** Present a numbered list of proposals: ``` Proposals: 1. ADD to kubernetes.md: "" Source: cluster-bootstrap/memory/gotchas-k8s.md 2. UPDATE validation.md: "" Source: cluster-bootstrap/memory/process-lessons.md 3. REMOVE helm.md: "" Reason: Source gotcha removed in cluster-bootstrap commit abc1234 ``` Wait for the user to approve, modify, or reject proposals. The user may say "all", give specific numbers, or ask for changes. ### Step 5: Apply approved changes For each approved proposal: - **ADD**: Append the new entry to the target file, matching the existing style (heading level, bullet format, explanation depth) - **UPDATE**: Edit the existing entry in place - **REMOVE**: Delete the entry from the file If a new best-practices topic file is needed: - Create it following the format of existing files (top-level heading, subheadings per entry, 2-6 lines per entry) - Add it to `~/dev/claude/projects/best-practices/BESTPRACTICES.md` with a one-line description ### Step 6: Update distill state Write `~/dev/claude/projects/best-practices/.distill-state.json`: ```json { "version": 1, "last_run": "", "projects": { "": { "path": "", "last_sha": "", "last_run": "" } } } ``` Preserve entries for projects that weren't processed this run (no changes). ### Step 7: Summary Print: - Projects scanned and number of changed memory files per project - Number of proposals (add/update/remove) - Number approved and applied - Any new best-practices files created ## Quality checks - Best practices must be **project-agnostic** — no hardcoded IPs, namespaces, or service names - Each entry should include the **principle and reasoning**, not just the rule - Entries must be **deduplicated** against existing best-practices content - The **BESTPRACTICES.md** must stay accurate after any file additions - Proposals are **always presented before applying** — never auto-apply