Thinking OS v1.0.0

Thinking OS is a set of Agent Skills for thinking work. This first release ships one skill: understand.

understand

Turns a polished document (proposal, report, deck, plan, PDF, Word, spreadsheet) into a short brief a careful colleague might write: two or three paragraphs that carry the document's critical path, then 3-5 questions for the author that the reader can send unchanged.

What it does:

• Reads the full source with page-preserving extraction; renders chart pages as images when values and labels come apart in the text layer.
• Separates what the document establishes from what stands on models, examples, or assertions, with page references inline.
• Generates evidence-first questions: what real-world fact would settle each weak claim, and if the evidence does not exist yet, what is the author's plan and by when.
• Holds the full evidentiary analysis (evidence tables, reconciliations, epistemic labels) and produces it only on request.
• Never recommends, rewrites, decides, or judges the author. Understanding and review leverage only.

Output discipline: a 600-word hard ceiling, plain human prose, no dashes-and-glyph apparatus, no analyst jargon in questions. The writing rules and the cognitive-load lint that enforces the mechanical subset live in the repo.

Install

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

Then, in Claude Code:

/understand path/to/document.pdf

Requires Node 20+ for the document-conversion fallback; poppler (brew install poppler) recommended for page-accurate PDF reading.

Evaluation

The repo ships the evaluation stack the skill is held to: a 13-dimension rubric (faithfulness, quantitative integrity, question quality, cognitive load, among others), invariants with release blockers, deterministic lints over the packet exemplars, and 15 output cases including compression and evidence-first question generation.