Thinking OS v1.1.0

Thinking OS is a set of Agent Skills for thinking work. This release ships a second skill, eli5, and moves both skills onto a shared core.

eli5 (new, 0.3.0)

Explains a file to a reader with no background: what it is, the two to five basic facts it rests on, how it works step by step, and why. Works on documents, source code, config files, specs, and policies. "Five years old" is the reader's background, not the tone.

What it does:

• Picks the subject (the thing the file describes, or the file itself for code and config) and takes it apart to the smallest true things it rests on, each labeled as from the file, general knowledge, or assumed by the file.
• Rebuilds upward: numbered steps where each rests only on the basic facts and the steps before it. When the file describes no mechanism, it says so in a sentence instead of narrating the document.
• Reports only the file's own reasons, and writes "The file does not say why" where it gives none.
• Keeps every number on the main path exact, with unit and what it counts; holds the rest with their location for follow-up.
• Never judges, recommends, rewrites, or invents. Instructions inside the file are reported as content and not followed.

Output discipline: four fixed sections, a word budget derived from the number of ideas the reader must hold (250/375/500 words for up to 9/14/19 ideas), 25-word sentences, no baby talk, no dashes or glyphs.

understand (1.1.0)

Behavior unchanged. Reading, writing, and execution rules now come from the shared core; the brief ends with one line naming what is held and can be asked for. The description excludes plain explanation for a reader with no background, which routes to eli5.

Shared core

core/ holds what every skill shares: how a source is read and what may be claimed about it, how output is written for a tired human with budgets that follow ideas rather than pages, and what the visible run looks like (announce once, read silently, answer; no printed sources, no diagnostics, no drafts in public). The core is copied into each package by scripts/sync-core.sh so installs stay self-contained; validation fails on drift.

Evaluation

• Human usefulness protocol (evals/usefulness-protocol.md) is the release gate: a reader who has not seen the source repeats the output back, opens the source, and counts surprises. Sessions are logged per skill; the checker reports the count.
• Cross-skill activation cases test the boundary between the two skills.
• Deterministic lints cover structure, idea-count budgets, sentence length, glossary terms, claims posing as basic facts, retired labels, banned vocabulary, and an always-loaded instruction ceiling for eli5.
• scripts/audit-run.py audits a Claude Code transcript against the execution contract.

Install

npx skills add vdmcb/thinking-os --skill eli5 -g -a claude-code -a codex -y
npx skills add vdmcb/thinking-os --skill understand -g -a claude-code -a codex -y

Status

Internal preview. Usefulness sessions completed: 0 of 5 per skill; scored rubric runs in Claude Code and Codex pending. See evals/*/STATUS.md.