deballast

A round-trip integrity test for specs. Compress, reconstruct, diff — see what's load-bearing, what's filler, and what your compression accidentally lost.

deballast reads a spec, compresses it to 3–7 falsifiable propositions, then reconstructs the spec from those propositions only — with no access to the original. It then diffs the reconstruction against the original, classifying every claim as load-bearing, decorative, or accidentally lost. The diff is the value: it makes visible which parts of the original carry weight and which parts are rephrasing.

What the diff looks like

Run on McKinsey's public Transformation services page (page state captured 2026-05-10):

$ deballast mckinsey-transformation.md --max-propositions 5 --mode strict

  878 words
  4 propositions, 5 consciously dropped
  7 load-bearing / 10 decorative / 0 accidentally lost
  $0.0006, 19.9s

Sample of what the diff classified as decorative (cuttable without loss of intent), with verbatim quotes from the page:

### Decorative (dropped without loss)
- "talent meets audacity" — Motivational framing, not a constraint.
- "We push for far-reaching ambition beyond performance improvement"
    — Generic aspiration, no specific claim.
- "We engage and energize people across an entire business, inspiring an
   organization's talent to not just think differently but to act"
    — Aspiration, not a service feature.
- "We drive execution and track impact at a relentless pace, where people,
   processes, and tools work together seamlessly"
    — Fluff, not a substantive constraint.
- (... 6 more items, full report omitted for brevity)

What the diff classified as load-bearing (the actual falsifiable claims McKinsey makes):

• Service is paid consulting for large-scale cross-functional change
• Proprietary method covering five impact dimensions (Financial & Operational, Employee, Customer, Capability, Environmental & Social)
• Outcome-aligned commercial agreements
• Digital tools Wave and RTS for tracking
• Senior practitioners include former C-suite executives
• Applicable across all industries
• Targets rapid, enduring change beyond incremental

Math: 7 load-bearing + 10 decorative + 0 accidentally-lost = 17 substantive claims. 10 of 17 (59%) are decorative. The diff cites every line.

What's actually new here

Two architectural choices distinguish Deballast from compression tools:

The diff distinguishes consciously-dropped from accidentally-lost. The compression stage doesn't just produce propositions — it also self-reports what it considered load-bearing but couldn't fit within the proposition budget. The diff then subtracts those intentional cuts from the "lost" classification. This separates two failure modes that summarizers conflate:

• Compression chose to drop X because it didn't fit — a decision, not a failure.
• Compression missed Y entirely — a real gap the user should know about.

The reconstruction is generated from propositions only. No access to the original. That's what makes the diff a genuine integrity test: if the propositions are too thin, the reconstruction loses things, and the diff makes those losses visible with reasons cited.

Most compression tools tell you what's there. Deballast tells you what isn't actually there.

Install

npm install -g @wytcab/deballast

Set your DeepSeek API key (Deballast uses DeepSeek V4 Flash by default):

export DEEPSEEK_API_KEY=sk-...

Use

deballast spec.md

Defaults: 7 propositions, strict mode. For a tighter compression on a verbose spec:

deballast spec.md --max-propositions 5 --mode strict

To save the report:

deballast spec.md --output spec.deballast.md

Three LLM calls per run: compression → reconstruction → diff. Each is independent. Cost typically lands $0.001–$0.01 on V4 Flash; specs over 5,000 words may run higher because diff output scales with input length.

What you get

A markdown report with five sections:

1. Propositions — the smallest set of falsifiable claims that capture the spec's intent.
2. Consciously dropped — items compression knew were load-bearing but couldn't fit.
3. Reconstruction — a spec generated from propositions only.
4. Fidelity diff — three buckets with reasons cited per item:
   • Load-bearing (preserved in propositions)
   • Decorative (dropped without loss)
   • Accidentally lost (gaps the diff caught)
5. Verdict — one paragraph: over-specified, under-specified, or roughly right.

Why not just use a summarizer?

A summarizer gives you a shorter version of the document. Deballast gives you a round-trip integrity test of the document. The reconstruction is generated from propositions alone, so the diff exposes which parts of the original carry weight and which parts are rephrasing. Summarizers tell you what's there. Deballast tells you what isn't actually there.

Built on the lens framework

Deballast is one lens. The framework is open and accepts more.

@wytcab/projection-core is the open framework Deballast is built on — corpus reader, prompt-template loader, LLM provider, lens interface. Other lenses share the framework instead of reinventing the plumbing.

@wytcab/nousboot is a pre-flight briefing lens for agent coding sessions. Same framework, different transformation.

You can write your own lens against projection-core — corpus in, structured output out, four wrappers (CLI, MCP, Paperclip, Claude Code skill) for free. See projection-core's README.

Integrations

• CLI: deballast (this binary)
• MCP server: deballast-mcp (stdio transport; works with Claude Desktop and other MCP clients)
• Paperclip: extension manifest in paperclip-extension.json
• Claude Code: skill in .claude/skills/deballast/SKILL.md

License

MIT.