Index of every page on this site: llms.txt
All skills
wado-lang avatar

/distill

@b208ba0
by Wadowado-lang/wado121 stars
2
Run it yourself

Cut the branch down to what the code cannot say: reuse what exists, remove duplication, dead code, and wasted work, turn invariants into asserts, and delete the comments the code already speaks. Run it after answering review feedback too — a fix written to satisfy a reviewer is the least distilled code on the branch.

  • 1 file
  • 4.8 KB
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/wado-lang/wado/distill

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈82 tokens for metadata: the name and description. ≈1.1k when used: this file.

Description uses 4.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈328 characters, or 4.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Distill

Scope

B=$(git merge-base origin/main HEAD)
scripts/changed-sources.sh              # the files, one per line
git diff "$B" --stat -- $(scripts/changed-sources.sh)
git diff "$B" -- $(scripts/changed-sources.sh)

Every file that reports, whatever its type, plus any doc it made stale. Whatever you notice on the way in is in scope too, pre-existing or not. A WEP keeps the sections docs/AGENTS.md requires.

Generated files are the one exclusion, and the script is what applies it: .gitattributes marks them linguist-generated, so a new generated path is excluded the moment it is marked and nothing here lists paths a second time. A plain git diff buries the branch under them — on a generator change they outnumber the sources five to one. Read the sources; regenerate the rest.

This is the scope on every run. Distilling again means the whole branch again, never the diff since the last distill: an earlier pass is not a clean bill, and what the code between the two commits made stale is spread across everything the branch touched.

Answering review feedback is one of the times to run it. Such a fix is written to satisfy a reviewer rather than to fit the code, so it arrives with the reviewer's framing in its comments, an explanation of the bug beside the fix, and often a helper the codebase already had.

Rules

Distilling keeps what the code does. The only change of behaviour it makes is a bug fix, and a bug fix starts from a failing test.

Code

  • Reuse: don't re-implement what the codebase already has. Grep the shared modules and the files next to the change, and call the existing helper.
  • Duplication: one behaviour, one implementation. Hoist the shared part of near-copies behind the difference — a parameter, a closure, an enum. Don't abstract a single use.
  • Altitude: a special case layered on shared infrastructure means the fix sits too shallow. Generalize the mechanism instead.
  • Dead code: delete what the change left behind.
  • Efficiency: cut wasted work — recomputation, repeated I/O, independent work run in sequence. A stored closure pins everything it captured; prefer a struct holding only the fields it needs.
  • Contracts, not defences: a function states what it requires and trusts its callers. Defensive programming is banned. A default or a fallback whose validity you cannot argue is the smell. It turns a broken call into a wrong answer that no test will catch. Write assert! for what the caller owes and unreachable! for the arm that cannot happen, and say which caller establishes it where that is not obvious. A branch that genuinely can happen is control flow and stays; the ban is on inventing an answer for a case you have not shown to be reachable.

Comments

Apply AGENTS.md § General Rules to every comment in scope. A comment saying what the code does is a rename or a decomposition to make. A comment stating an invariant is an assert to write. A comment that carries no information is deleted outright.

Markdown

Apply the markdown skill to every Markdown file in scope.

In an instruction file (an AGENTS.md, a skill), also cut a rule that is trivially deduced from a principle the file or the root AGENTS.md already states: detail dilutes the rules that matter. Keep one that fences a principle against a reading broader than intended.

Cut words, never a fact. A measurement, a name to grep for (a pass, a type, a function), a condition or an exception, and the bug behind a rule are facts, not detail. Before removing a passage, grep for what links to it. Keep a code block runnable on its own: every name it uses defined in it, every command and path real. Run only a block without side effects to check it.

Sweep by shape

A copy does not share a name, so grepping the name finds nothing.

For every predicate or helper the branch adds or moves, grep the tree for what its body looks like rather than what it is called. Two or three tokens of the body carry further than a signature.

Finish the sweep in the same pass. Fixing the sites a reviewer named and calling it a class fix leaves the rest standing, and the next review returns them one at a time.

Cycle

Three passes over that scope; surviving one is no exemption. Stop when a pass finds nothing to cut.

Finish

mise run format

Code edits: run the tests covering what you touched (mise run test, mise run test-wado). Comment, doc, and Markdown edits alone need only mise run check, which holds the specification's examples to their fixtures.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at b208ba0. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago

README badge

README badge for wado-lang/wado/distill