raisin — Dense Python for Machine Readers

READER: LLM_agent
AUDIENCE_OF_OUTPUT: LLM_not_human
OPTIMIZATION: token_efficiency + functional_correctness
CONSTRAINT: 100_percent_functional_parity
METRIC_PRIMARY: cl100k_tokens
METRIC_SECONDARY: test_pass_rate
FORBIDDEN: docstrings, explanatory_comments, ceremonial_type_hints
REQUIRED: all_tests_pass, all_public_api_preserved

The metaphor: a raisin is a grape with the water removed. Same nutrients, same sweetness, same fruit — half the mass. This skill does the same thing to your Python: removes the water (docstrings, boilerplate, ceremonial type hints), keeps the nutrients (logic, behavior, public API).

---

WHEN TO INVOKE

trigger_conditions:
  explicit: user says "/halfcode", "/dense", "/raisin", "write dense", "no docstrings"
  implicit_greenfield: |
    user is writing new Python code for LLM-read consumption
    (check: no human plans to browse the source; tests are the contract)
  implicit_retrofit: |
    user asks to compress, minimize, or reduce tokens in existing Python code

do_not_invoke:
  - "writing library code intended for human contributors"
  - "writing tutorial or example code for documentation"
  - "writing code where __doc__ or help() is used at runtime"
  - "user explicitly requested verbose/readable style"

---

FRAMING (why this exists)

problem: |
  LLMs are trained to reproduce human coding conventions — docstrings for Sphinx,
  type hints for IDE hover, verbose error handling for readable stack traces.
  None of these serve the LLM that writes or reads the code.
  Every token of human-imitation overhead is a token of context window burned.

solution: |
  Write code for machine reading. Preserve runtime behavior and public API
  exactly. Drop everything that exists only for human eyes.

proven_savings:
  greenfield: 48-52% fewer tokens vs normal Python
  retrofit: 37-80% fewer tokens vs original, library-dependent
  test_pass_rate: 100% across all verified experiments (786 tests)

reference: https://github.com/Oldrich333/raisin

---

WHAT TO PRESERVE (never touch)

public_api:
  class_names: keep_exact
  public_method_names: keep_exact
  public_function_names: keep_exact
  public_parameter_names: keep_exact  # callers pass them as keyword args
  public_parameter_defaults: keep_exact

test_contracts:
  error_message_strings: keep_exact_if_tested  # grep tests/ for the string first
  gettext_calls: keep_as_literals  # _(...) — xgettext breaks on concatenation
  exit_codes: keep_exact
  stdout_output: keep_byte_exact

runtime_contracts:
  import_paths: keep_exact_or_update_consumers
  __slots__: keep_if_present
  metaclass: keep_if_present
  __init_subclass__: keep_if_present

---

WHAT TO REMOVE (always waste)

docstrings:
  what: '"""..."""  blocks inside functions/classes/modules'
  action: delete
  exception: "only if __doc__ is accessed at runtime (rare — Click --help does NOT use docstrings)"

comments:
  what: "# explanatory comments"
  action: delete
  keep: "# type: ignore, # noqa, # pragma: no cover (tool pragmas)"
  keep: "# WHY comments when logic is genuinely non-obvious (rare)"

blank_lines:
  between_class_methods: 0
  between_top_level_defs: 1
  double_blanks_anywhere: never

internal_type_hints:
  before: "def _helper(s, value: t.Any, param: Parameter | None, ctx: Context | None) -> t.Any:"
  after:  "def _helper(s, value, param=None, ctx=None):"
  keep_on: "public __init__ signatures where IDE hover matters"

overload_stubs:
  what: "@t.overload def foo(...) -> X: ..."
  action: "delete — runtime no-ops, only matter to type checkers"
  exception: "keep if project runs mypy --strict in CI"

trivial_wrappers:
  what: "def _helper(x): return some_func(x)"
  action: "inline if called < 3 times"

---

WHAT TO RESTRUCTURE (the real wins)

repeated_error_patterns:
  detect: "3+ occurrences of if/raise or print/return-code pattern"
  fix: "module-level lambda or tiny helper"
  example_before: |
    if not args:
        print("Error: Missing argument", file=sys.stderr)
        return 2
    try:
        item_id = int(args[0])
    except ValueError:
        print("Error: Invalid id", file=sys.stderr)
        return 2
  example_after: |
    E = lambda m, c=1: (print(f"Error: {m}", file=sys.stderr), sys.exit(c))
    # usage:
    if not args: E("Missing argument", 2)
    try: item_id = int(args[0])
    except ValueError: E("Invalid id", 2)

repeated_validation_patterns:
  detect: "multiple functions doing: load → find → error-if-missing → act"
  fix: "shared helper returns validated state"
  example: |
    def _get(args, cmd):
        need(args, cmd); i = pid(args[0]); d = load(); x = find(d, i)
        if not x: E(f"No item with id {i}")
        return d, i, x
    # reused by cmd_done, cmd_rm, cmd_show — eliminates ~30 duplicate lines

repeated_dispatch:
  detect: "if cmd == 'add': ... elif cmd == 'list': ..."
  fix: "dict lookup"
  example: "CMDS = {'add': c_add, 'list': c_list, ...}; CMDS[cmd](args)"

repeated_attribute_assignment:
  detect: "10+ lines of s.x = x in __init__"
  fix_small: "s.a, s.b, s.c = a, b, c  # tuple unpacking"
  fix_large: "vars(s).update({k: v for k, v in locals().items() if k != 's'})"

repeated_inheritance_check:
  detect: "8+ occurrences of 'if X is None and parent is not None: X = parent.X'"
  fix: |
    _inh = lambda val, attr, d=None: val if val is not None else (getattr(parent, attr) if parent else d)
    s.terminal_width = _inh(terminal_width, "terminal_width")
    s.max_content_width = _inh(max_content_width, "max_content_width")

---

NAMING RULES

public_names: unchanged
internal_scope_renames:
  self: s
  result: r
  value: v
  data: d
  params: ps
  options: opts
  kwargs: kw
  flags: fl
  command: cmd
  context: ctx
  buffer: buf
  widths: w
  indent: ind
  wrapper: W
  formatter: fmt

principle: |
  Inside a function/method, short names are fine because the LLM sees the
  full scope in one view. At module level or across files, longer names help
  navigation.

single_letter_conventions_ok:
  - "i, j, k — loop indexes"
  - "f — file handle or function"
  - "x, v — item in iteration"
  - "e — exception"
  - "s — self (established dense-style convention)"
  - "r — return value"

---

FORMATTING RULES

semicolons:
  rule: merge sequential short statements with ;
  example: "s.name = name; s.mode = mode; s.buf = []"
  limit: "keep lines under ~120 chars"

one_line_methods:
  rule: single-expression methods fit on one line after the colon
  example: "def write(s, string): s.buffer.append(string)"

inline_conditionals:
  rule: if/return with one statement can be one line
  example: "if not items: return print('No todos.') or 0"

comprehensions:
  rule: replace all loop-append patterns
  before: |
    rv = []
    for x in items:
        if cond: rv.append(x)
    return rv
  after: "return [x for x in items if cond]"

blank_lines:
  between_classes: 1
  between_module_functions: 1
  between_class_methods: 0
  end_of_file: "single newline"

imports:
  merge: "from x import a, b, c  (not three lines)"
  multi_stdlib: "import os, sys  (single-line for stdlib aggregates)"
  keep_separate: "TYPE_CHECKING block, conditional imports"

---

VERIFICATION PROTOCOL (mandatory after every change)

step_1_syntax:
  command: 'python3 -c "import ast; ast.parse(open(FILE).read())"'
  expected: silent success
  on_fail: fix syntax, do not proceed

step_2_tests:
  command: "pytest tests/ -q --tb=short"
  expected: "100% pass"
  on_fail: "fix the code, NEVER modify tests to pass"

step_3_tokens:
  command: |
    python3 -c "
    import tiktoken
    enc = tiktoken.get_encoding('cl100k_base')
    print(len(enc.encode(open(FILE).read())))
    "
  expected: "lower than baseline"

common_bug_patterns:
  closure_capture_changed: "inlining a helper changed which variables are captured"
  mutable_default: "def foo(x=[]) — use x=None then x = x or []"
  walrus_scope_leak: "walrus in if-test persists variable after the block"
  error_string_drift: "test asserts exact text, small edit broke it"
  gettext_concatenation: "_() must wrap the whole literal, not be concatenated"

---

CHECKLIST — grep patterns to scan

Run these over the code. Each hit is an optimization opportunity.

search_patterns:
  docstrings:        {grep: '^\s*"""', action: delete}
  repeated_raise:    {grep: 'raise \w+Error\(', action: "3+ hits → extract lambda"}
  print_return:      {grep: 'print\(.*file=sys\.stderr\).*return [12]', action: "extract E helper"}
  multi_line_if_raise: {grep: 'if [^:]+:\n\s+raise', action: "collapse to one line"}
  long_type_hints:   {grep: 't\.Any|Parameter \| None', action: "drop from internal methods"}
  inheritance_check: {grep: 'if \w+ is None and parent', action: "extract _inh helper"}
  trivial_helper:    {grep: 'def _\w+\([^)]*\):\s*return \w+\(', action: "inline if < 3 callers"}
  overload_stub:     {grep: '@t\.overload', action: "delete runtime no-op"}
  if_elif_chain:     {grep: 'elif .*==\s*[\"\\\']\w+[\"\\\']:', action: "convert to dict"}
  loop_append:       {grep: 'rv\s*=\s*\[\][\s\S]*?\.append\(', action: "list comprehension"}
  blank_in_class:    {grep: '^\s+def .*:\n\s*\n\s+def ', action: "remove blank"}

---

GREENFIELD vs RETROFIT

greenfield:
  when: "writing new code from scratch"
  process:
    1: "write spec and tests first"
    2: "write dense from line 1 (this skill's rules)"
    3: "run tests, fix bugs"
    4: "measure tokens"
  expected_savings: "~48-52% vs normal Python style"
  effort: low

retrofit:
  when: "compressing existing code"
  process:
    1_strip: "AST-based docstring/comment strip (automated, saves 25-47%)"
    2_rewrite: "rewrite each file from scratch using stripped version as reference"
    3_test: "run tests after each file"
  expected_savings: "40-65% depending on original verbosity"
  effort: "medium to high per file"

retrofit_ceiling:
  why: "original API, architecture, and algorithm choices constrain restructuring"
  implication: "greenfield is cheaper AND denser than retrofit"
  recommendation: "if given a choice, start dense. Retrofit only when API must be preserved."

---

EXAMPLE: TODO CLI (greenfield, verified)

spec: "CLI TODO with 10 commands, JSON storage, filters, import/export"
tests: 28
normal_python: {tokens: 3022, loc: 437}
dense_python:  {tokens: 1458, loc: 104}
savings: 52%
verification: "both implementations pass 28/28 identical tests"

Excerpt from the dense version showing key patterns:

import json, os, sys
from datetime import datetime
from pathlib import Path

F = Path(os.environ.get("TODO_FILE") or Path.home() / ".todo.json")
PRI = ("LOW", "MED", "HIGH")
E = lambda m, c=1: (print(f"Error: {m}", file=sys.stderr), sys.exit(c))

def ld():
    try: return json.loads(F.read_text())
    except Exception: return {"items": [], "next_id": 1}

def sv(d):
    F.parent.mkdir(parents=True, exist_ok=True)
    t = F.with_suffix(F.suffix + ".tmp"); t.write_text(json.dumps(d, indent=2)); t.replace(F)

def _get(a, c):
    need(a, c); i = pid(a[0]); d = ld(); x = find(d, i)
    if not x: E(f"No todo with id {i}")
    return d, i, x

def c_done(a, kw, fl):
    d, i, x = _get(a, "done"); x["done"] = True; sv(d); print(f"Done #{i}: {x['text']}"); return 0

def c_rm(a, kw, fl):
    d, i, _ = _get(a, "rm"); d["items"] = [x for x in d["items"] if x["id"] != i]
    sv(d); print(f"Removed #{i}"); return 0

Notice: E lambda for errors, ld/sv for storage, _get helper shared by done/rm/show, zero blank lines, short internal names, merged imports, one-line methods where appropriate.

---

REFERENCE: VERIFIED EXPERIMENTS

experiments:
  click_8_2_1:
    original_tokens: 81845
    rewritten_tokens: 36381
    savings: 55.5%
    tests: 738_of_738_pass
  flask_3_1_3:
    original_tokens: 49021
    rewritten_tokens: 18271
    savings: 62.7%
  bottle_0_13_4:
    original_tokens: 39901
    rewritten_tokens: 24890
    savings: 37.6%
  greenfield_todo:
    normal_tokens: 3022
    dense_tokens: 1458
    savings: 51.8%
    tests: 28_of_28_pass
  guide_validation_urlshort:
    normal_tokens: 1467
    agent_tokens: 775
    savings: 47.2%
    tests: 20_of_20_pass
  guide_validation_click_formatting:
    original_tokens: 2150
    agent_tokens: 1195
    savings: 44.4%
    tests: 738_of_738_pass

single_file_record:
  flask_helpers_py: {from: 5399, to: 1064, saved: 80.3%}

total_tests_verified: 786

---

RESPONSE FORMAT (when invoked)

When you apply this skill, work in this order:

1. Read the target file(s) fully before writing anything
2. Identify public API — list classes, methods, parameters that callers depend on
3. Identify test contracts — grep for error strings in tests if available
4. Write the rewrite — apply REMOVE + RESTRUCTURE + NAMING + FORMATTING rules
5. Verify — syntax, tests, tokens
6. Report — starting tokens, final tokens, % saved, test result

Do NOT:

• Explain the philosophy in your response (the user already chose this skill)
• Output intermediate "thinking" about patterns — just apply them
• Preserve code purely for human readability (that's the opposite of the goal)
• Modify tests to pass (fix the code instead)

Do:

• Trust your intelligence to find compression opportunities the checklist missed
• Apply aggressive restructuring, not just cosmetic formatting
• Always verify tests pass — 100% functional parity is non-negotiable