distill-transcripts

Files (4)

• SKILL.md
• extract-actions.sh
• extract-prompts.sh
• query-actions.sh

SKILL.md (first lines)

Read the project's transcripts for work that repeats, both the work the user
asks for and the work you do to satisfy it, then propose a remedy for each
pattern nothing already covers. Build nothing unless the user picks it.

Arguments: $ARGUMENTS

Read the transcripts of the project directory named in the arguments, or of the
current working directory if the arguments name none. If they ask for every
project (say, "all transcripts"), pass `--all`. If they name a focus area
instead (say, "testing" or "anything involving jj"), read the current project's
transcripts and keep only candidates in that area.

Load `/distill` first. It covers reducing a body of data to an artifact. This
skill supplies the data (transcripts), the question ("what work recurs?"), and
the artifact (a proposal list).

# Workflow

1. Run `extract-prompts.sh` (in this skill's directory) with the project
   directory as its argument, or `--all` for every project, writing its output
   to a file in the scratchpad directory. It prints one tab-separated `project`,
   `session id`, `timestamp`, `prompt` line per prompt, so `wc -l` gives the
   prompt count and `cut -f2 | sort -u` the session count. Pass
   `--max-chars 900` when the prompts are too long to read whole: it keeps each
   request and marks how much it cut. For a pasted log or a plan, that is all
   you need. Say in the report that you truncated. When the project has no
   transcripts it exits with an error. Report that and stop
2. Run `extract-actions.sh` (in this skill's directory) with the same argument,
   writing its output to a second file in the scratchpad directory. It prints
   one line per tool call, from the main thread and from the subagents a session
   spawned, with each tool's input reduced to a signature. Never read this file
   whole. See "Reading the action extract"
3. Enumerate what already covers repetitive work here, before reading a single
   prompt, so you judge candidates against a fixed list. See "Enumerating
   existing coverage"
4. Read every extracted prompt. Call none irrelevant before you read it
5. Cluster the prompts by what the user wanted, not by the words used. "Rewrite
   this so each function stays at one level" and "this reads bottom-up, fix it"
   are one task. For each cluster, keep every prompt in it, the sessions it
   spans, and two or three verbatim examples showing the range. See "What counts
   as repetitive work"
6. Cluster the actions. See "Reading the action extract"
7. Judge each cluster against the enumeration. See "Judging existing coverage"
8. For each surviving candidate, choose the remedy. See "Choosing a remedy",
   then "Choosing a level" for the remedies that have one
9. Report as in "Reporting". Offer to build the ones the user picks: run
   `/create-skill` for a skill, `/update-config` for a hook or a permission
   entry, and write a rule, script, or fix yourself

# Enumerating existing coverage

List what already exists, with a one-line summary of each:

- User skills: `~/.claude/skills/*/SKILL.md`
- Project skills: `<project>/.claude/skills/*/SKILL.md`
- Project commands: `<project>/.claude/commands/*.md`
- Plugin and built-in skills: the ones listed in this session's available-skills
  list
- Rules: `~/.claude/CLAUDE.md` and every `CLAUDE.md` in the project
- Hooks and permissions: the `hooks` and `permissions` keys of
  `~/.claude/settings.json` and the project's `.claude/settings.json`
- Scripts: the project's `package.json` scripts, `Makefile` targets, and
  whatever it keeps in `scripts/` or `bin/`

Count them by kind. The report opens with those counts. Read every summary, and
the body of anything close to a candidate. A name is not a procedure. Only the
body describes what it does.

# What counts as repetitive work

A cluster is a candidate when all of these hold:

- It holds three or more prompts spanning two or more sessions. One elaborate
  request is not a pattern; three plain ones are. Prompts repeated inside a
  single session count as one, because they are one task restated
- The user wanted the same outcome each time, whatever the phrasing
- The next occurrence is likely. A migration that finished last month will not
  come up again

A cluster that meets the last two but holds two prompts, one per session, is
borderline. Report it in a separate list of weaker candidates. Never drop it
silently.

The counts are the argument. A proposal without prompts behind it is your taste,
presented as evidence.

Corrections tell you more than plain requests do. A prompt that corrects what
you did ("no, split that into separate commits first") states a procedure the
user expects and you missed. Several such prompts across sessions form one
candidate.

Other kinds of clusters worth keeping:

- A preference restated in different projects or files
- A sequence the user walks you through step by step, the same way each time
- A command invoked repeatedly with the same hard-to-remember flags
- A prompt that is nothing but context you could have looked up yourself: a file
  path, a command's flags, a convention already written down
- Requests that already invoke a skill and then correct its output: evidence to
  amend that skill, not to add one

These aren't exhaustive. Reason from first principles when none fits cleanly.

# Reading the action extract

A prompt cluster shows what the user asked for more than once. An action cluster
shows what the same request cost: the commands re-derived, the files re-read,
the calls that failed before they worked.

`extract-actions.sh` prints one tab-separated line per tool call:

| Column | Contents                                                             |
| ------ | -------------------------------------------------------------------- |
| 1      | project                                                              |
| 2      | session id                                                           |
| 3      | timestamp                                                            |
| 4      | tool name                                                            |
| 5      | signature: `Bash:jj diff`, `Edit:src/parse.py`, `Skill:humanize`     |
| 6      | `err` when the call returned an error, empty otherwise               |

From TomerAberbach/claude-config, MIT.

More from TomerAberbach/claude-config