Theorist

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 understanding shifts meaningfully:

• A root cause is identified that changes the approach.
• A strategy pivot happens (tried X, learned Y, now doing Z).
• A key discovery narrows or expands the problem scope.
• The systematic approach crystallizes or changes direction.
• An open question gets answered, or a new uncertainty emerges.

Do NOT update on every small code change. Update when the theory changes, not when the code changes.