Theorist

---

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:

undefined

What THEORY.MD Is Not

undefined

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