Theorist — Productivity skill for Claude Code

---

name: theorist description: | Maintain a per-repo THEORY.MD as a continuously updated narrative of the operating theory behind the current work. Activates EVERY session and stays active throughout the session. Requires frequent in-session rewrites as new learnings land (major result, verification outcome, or strategy pivot). Not a log, not a plan, not a todo list — a cohesive document describing the higher-level thinking, systematic strategy, and motivation behind the work as it evolves. Updated end-to-end (rewritten, not appended) as understanding deepens. author: blader version: 1.3.0 date: 2026-02-28

Theorist

You maintain a per-repo narrative document at `THEORY.MD` that captures the operating theory of the work being done. This is not a plan, not a log, not a task list. It is a living essay that describes *why* the work exists, *what* the systematic strategy is, and *how* the current approach connects to the larger picture.

**This skill is always active during every session. No trigger required.** **Once active in a session, it stays active for the full session.**

What THEORY.MD Is

A cohesive narrative document — typically 1-3 pages — that a thoughtful collaborator could read to understand:

• The problem thesis: What problem is being solved and why it matters. Not "fix bug X" but "the export pipeline assumes Y, which breaks under Z."
• The operating theory: The current mental model of how the system works and where the leverage points are. What has been tried, what was learned, and what that implies about the shape of the solution.
• The systematic strategy: Not task-by-task steps, but the higher-order approach. Why this sequence of work? What principle connects the changes?
• Key discoveries and pivots: Moments where understanding shifted. What was the old theory, what broke it, and what replaced it.
• Open questions and uncertainties: What is still unknown. Where the current theory might be wrong. What would change the approach.

What THEORY.MD Is Not

• Not a changelog or log: Never append timestamped entries. The document is rewritten holistically as understanding evolves.
• Not a plan or todo list: No task items, checkboxes, or step-by-step instructions. A plan says "do X then Y." A theory says "X matters because of Y, and the right lever is Z."
• Not a postmortem: Written in the present tense of ongoing work, not retrospectively about completed work.
• Not a status report: No "today I did X." Instead: "The current approach is X because the evidence shows Y."

Session Behavior

Starting a Session

At session start, if `THEORY.MD` exists, read it. Use it to orient yourself to the work. Do not announce that you read it.

If meaningful work begins and no THEORY.MD exists yet, create one once you have enough context to write a meaningful narrative (not before — don't create an empty skeleton).

During Work

Update THEORY.MD when underst