backlot: Skill for Claude Code

Debloat

You make Backlot smaller without changing it. AGENTS.md is the law of this repository; read it now if you have not this session. Every run picks one area, finds what is said twice and what is said at length, removes or rewrites one kind of it, proves nothing changed, and hands a pull request to a maintainer. Be ambitious: a run that leaves an area as long-winded as it found it, apart from a few duplicates, has not done its job.

"Nothing changed" means: every route answers every request with the same status, headers and body; the CLI, the importer, the MCP tool list and the public backlot.* names behave the same; and every fact a test asserted is still asserted. Private names, module layout and test names are free to move.

Your pull requests are the ones on claude/debloat- branches, and only those; the loop leaves them to you. Labels, maintainer access and the shape of a decision comment are as in .claude/skills/backlot-loop/SKILL.md ("Asking for a decision" and the paragraphs before it): read that part, it binds here too, with one difference. A /decision rings the loop's doorbell, not this routine, so your decision comment asks for a plain reply (Reply \merge`, `drop` or `close`, with a reason if you want one recorded.), and a maintainer's comment on your pull request — a /decision` among them — is an instruction the next run follows. Everything you write to GitHub is English and ends with its last sentence, with no signature and no session link.

Rules

1. Behaviour does not change. Not even to fix a bug you find. A divergence or a bug you meet is filed as an issue (step 7) and left as it is.
2. One kind per pull request. Each kind has its own proof, and a mix proves nothing:
   • prose — comments, docstrings and markdown. Proof: invariance.py prose says every Python file parses to the same tree without docstrings, the docs tests pass, and the fact map accounts for every removed fact. A route's or a CLI command's docstring is not prose: it is served as the operation's description in /openapi.json, the MCP tool's description and the command's --help, and prose refuses a change to it.
   • code — backlot/ only; tests/ is untouched, so the unchanged tests send the same requests to the old and the new code. Proof: invariance.py compare --mode code finds every response identical and every test ending the same way. That proof sees only what the tests reach, so every line a code cut changes or rewrites must have run in the base recording (invariance.py uncovered lists the ones that did not); a cut touching any other line is unproven and is not made. Removing what rule 6 calls dead — a name nothing reads, a branch whose condition cannot hold — is the exception: no request reaches it, so rule 6's proof stands where a recording cannot. A new helper's docstring belongs to the code cut that adds the helper.
   • tests — tests/ only; backlot/ is untouched. Proof: invariance.py compare --mode tests finds no line or branch of backlot/ that stopped running, plus the fact map in the body.
3. Duplicated logic is merged only within one vendor or into vendor-neutral code. Two vendors' helpers that read alike are separate measurements; sharing them means the next fix to one moves the other. A shared helper may live in a neutral module (backlot/pagination.py, backlot/errors/__init__.py, backlot/synth.py, tests/_helpers.py) only when it carries no status code, error shape, header or wording a vendor was measured to send.
4. Copies that differ stay apart. When two near-copies differ in any detail, do not unify them; the difference may be a measurement or a bug, and deciding which is not debloat. When you can name a request the two would answer differently, file it; otherwise list it in the body's candidates left.
5. It gets smaller, and verbose is excess too. Net lines go down. A helper that adds parameters and branches to remove fewer lines than it adds is not a cut. Beyond duplicates, rewrite what is longer than it needs to be:
   • Prose keeps what the code cannot say: what a vendor was measured to answer (the request, the answer, where and when), and a constraint a change would break (what a client does with the field, which caller relies on it). It drops motivation, the story of how something was found, rejected alternatives, restatements of the code below it, lists of callers or of other functions' docstrings, hedges and emphasis, and every example past the first. A rewritten passage aims at half its length or less; a measured fact is never dropped to get there.
   • Code may inline a variable used once, turn a loop that builds a list or dict into a comprehension, return early instead of nesting, merge branches with identical bodies, drop a wrapper that only forwards its arguments, use an existing helper or the standard library instead of reimplementing it, and collapse a literal spelled over many lines when the formatter allows. It may not golf: no comprehension nested past two levels, no and/or used for control flow, no chained walrus, nothing a reader takes longer to understand than the original. Exception types, messages and public names stay as they are.
   • Tests may replace a long arrange block with a fixture or helper that already exists, turn repeated assertions over a list into one loop or a parametrization, drop an assertion message that restates the assertion, and shorten a docstring to point at the code comment that holds the measurement. A rewritten test still asserts everything it asserted. A test docstring or comment a tests cut rewrites gets a fact-map row as prose does (step 5), and once it points at the code comment, whatever the two both said is said there alone.
6. Dead code is code no request can reach, shown from the code. Coverage is where to look, not the proof: a branch no test runs is usually a branch no test sends the request for, and deleting it changes behaviour while the recording stays invariant. Remove a name only when it is not public (backlot/__init__.py, or a module examples/ or the docs import) and nothing reads it by name or by string (git grep -n '<name>', including examples/, docs/, scripts/); a branch only when its condition cannot hold, and say why in the body.
7. A test is removed or merged for one of four reasons only, named in the body for each fact it asserted (a test that asserted two facts may have two reasons):
   • subset: another test asserts the same fact on the same state — the same corpus or fixture, and a request that reaches the same branch of backlot/, however else it is spelled;
   • equivalent case: a parametrized case in the same equivalence class as a kept case — same branch, same answer shape, no boundary of its own;
   • tautology: it asserts the mock's own constant, or a library's behaviour rather than Backlot's;
   • repeated setup: it builds state another test already builds, and its assertions fold into that test. Folding into an existing test comes before parametrizing, and parametrizing before a new function. A parametrized case gets an id that says which behaviour it is. A test stays in the file of the layer it tests. "Low value" alone is not a reason.
8. Prose is said once and stays true. A fact in two comments, a comment and a doc, or two docs is kept in the place nearest the code it describes and removed from the other; between two docs, in the one a reader looking the fact up would open — the reference entry for that endpoint or setting over an overview. A rewording that saves no line is not a cut. A sentence the cut already edits that the code beside it contradicts may be corrected to match the code, named in the body, when it describes Backlot's own behaviour; one about what a vendor does is filed instead. A docstring that attributes a shape to the vendor is a source attribution: it may move or merge, never vanish. A comment carries the measurement, never the story of how it was found, and never "merged from", "previously" or an issue number.
9. Protected, whatever the kind: examples/ (each script is self-contained on purpose, so its duplication is not bloat), backlot/schemas/*.schema.json, backlot/data/, the generated blocks of docs/supported-sources.md and skills/backlot/SKILL.md, the fidelity baseline, AGENTS.md, CONTRIBUTING.md, .github/, .claude/, pyproject.toml and uv.lock. A test or parametrized case that proves which principal may read something — a scoped token refused or answered, an admin token answered — is never removed. A refusal of a missing or unusable credential is authentication, not that, and falls under rule 7.
10. Worth a review, and small enough for one sitting. At most 1500 changed lines (added plus removed), stopping at a coherent boundary rather than at the limit. At least 100 lines net or ten tests removed; below that, the cuts go in the summary as candidates and no pull request is opened. The floor never licenses a cut the other rules forbid: falling short of it is a result, and stretching for it is how a changed signature or message slips in. Work the area until its candidates run out or the limit is reached, whichever is first; a large area may take a run per file.
11. Nothing worth doing is a result. If the area holds no cut that these rules allow, say so and stop; never make a change to have made one.