Skip to content
Back to search

theorist

A Codex/Claude skill that maintains per-repo operating theory documents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/blader--theorist/badge.svg)](/listings/blader--theorist)

HTML

<a href="/listings/blader--theorist"><img src="/api/listings/blader--theorist/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Use a skills directory for your client and clone into it:

SKILLS_DIR="${CODEX_SKILLS_DIR:-${CLAUDE_SKILLS_DIR:-$HOME/.codex/skills}}"
mkdir -p "$SKILLS_DIR"
git clone https://github.com/blader/theorist.git "$SKILLS_DIR/theorist"

If you already have the repo checked out, copy just the skill file:

mkdir -p "$SKILLS_DIR/theorist"
cp SKILL.md "$SKILLS_DIR/theorist/"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 165 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: theorist
  3. description: |
  4. Maintain a per-repo THEORY.MD as a continuously updated narrative of the
  5. operating theory behind the current work. Activates EVERY session and stays
  6. active throughout the session. Requires frequent in-session
  7. rewrites as new learnings land (major result, verification outcome, or
  8. strategy pivot). Not a log, not a plan, not a todo list —
  9. a cohesive document describing the higher-level thinking, systematic
  10. strategy, and motivation behind the work as it evolves. Updated end-to-end
  11. (rewritten, not appended) as understanding deepens.
  12. author: blader
  13. version: 1.3.0
  14. date: 2026-02-28
  15. ---
  16. # Theorist
  17. You maintain a per-repo narrative document at `THEORY.MD` that captures
  18. the operating theory of the work being done. This is not a plan, not a log, not
  19. a task list. It is a living essay that describes *why* the work exists, *what*
  20. the systematic strategy is, and *how* the current approach connects to the
  21. larger picture.
  22. **This skill is always active during every session. No trigger required.**
  23. **Once active in a session, it stays active for the full session.**
  24. ## What THEORY.MD Is
  25. A cohesive narrative document — typically 1-3 pages — that a thoughtful
  26. collaborator could read to understand:
  27. - **The problem thesis**: What problem is being solved and why it matters.
  28. Not "fix bug X" but "the export pipeline assumes Y, which breaks under Z."
  29. - **The operating theory**: The current mental model of how the system works
  30. and where the leverage points are. What has been tried, what was learned,
  31. and what that implies about the shape of the solution.
  32. - **The systematic strategy**: Not task-by-task steps, but the higher-order
  33. approach. Why this sequence of work? What principle connects the changes?
  34. - **Key discoveries and pivots**: Moments where understanding shifted. What
  35. was the old theory, what broke it, and what replaced it.
  36. - **Open questions and uncertainties**: What is still unknown. Where the
  37. current theory might be wrong. What would change the approach.
  38. ## What THEORY.MD Is Not
  39. - **Not a changelog or log**: Never append timestamped entries. The document
  40. is rewritten holistically as understanding evolves.
  41. - **Not a plan or todo list**: No task items, checkboxes, or step-by-step
  42. instructions. A plan says "do X then Y." A theory says "X matters because
  43. of Y, and the right lever is Z."
  44. - **Not a postmortem**: Written in the present tense of ongoing work, not
  45. retrospectively about completed work.
  46. - **Not a status report**: No "today I did X." Instead: "The current approach
  47. is X because the evidence shows Y."
  48. ## Session Behavior
  49. ### Starting a Session
  50. At session start, if `THEORY.MD` exists, read it. Use it to orient
  51. yourself to the work. Do not announce that you read it.
  52. If meaningful work begins and no THEORY.MD exists yet, create one once you
  53. have enough context to write a meaningful narrative (not before — don't create
  54. an empty skeleton).
  55. ### During Work
  56. Update THEORY.MD when understanding shifts meaningfully:
  57. - A root cause is identified that changes the approach.
  58. - A strategy pivot happens (tried X, learned Y, now doing Z).
  59. - A key discovery narrows or expands the problem scope.
  60. - The systematic approach crystallizes or changes direction.
  61. - An open question gets answered, or a new uncertainty emerges.
  62. Do NOT update on every small code change. Update when the *theory* changes,
  63. not when the *code* changes.
  64. ### Update Cadence (Strict)
  65. Theorist should refresh frequently during active work, not just at major
  66. milestones or session end.
  67. - Trigger an update after each major work loop:
  68. - investigate,
  69. - implement,
  70. - verify (tests/benchmarks/repro checks).
  71. - Trigger an update whenever verification materially changes confidence
  72. (new failure mode, passing fix confirmation, large benchmark shift).
  73. - Trigger an update when 2-3 meaningful learnings have accumulated, even if
  74. they happened close together.
  75. - If active work continues for ~10 minutes without a theory
  76. refresh, perform a concise rewrite that incorporates current learnings.
  77. - If multiple discoveries happen in a burst, batch them into one immediate
  78. rewrite after the burst; do not defer to session end.
  79. ### How to Update
  80. Rewrite the relevant sections of the document in place. The entire document
  81. should read as a coherent narrative at any point in time. Old theories that
  82. were superseded should be briefly noted as pivots ("Initially the hypothesis
  83. was X, but Y revealed that Z"), not deleted entirely — the evolution of
  84. understanding is part of the theory.
  85. Keep the document concise. Prefer clarity over completeness. A reader should
  86. be able to understand the full strategic picture in under 5 minutes.
  87. ## Document Structure
  88. THEORY.MD should flow as natural prose organized under a few clear headings.
  89. The exact structure should adapt to the work, but a typical shape:
  90. ```markdown
  91. # Theory: [Short Title of the Work]
  92. ## Problem
  93. [What problem exists, why it matters, what makes it hard. Not just symptoms
  94. but the structural reason the problem exists.]
  95. ## Operating Theory
  96. [Current mental model. How does the system actually work in the relevant area?
  97. What are the key dynamics? Where is the leverage?]
  98. ## Strategy
  99. [The systematic approach. Not tasks but principles. Why this sequence? What
  100. connects the individual changes into a coherent campaign?]
  101. ## Key Discoveries
  102. [Pivots in understanding. What was learned that changed direction. Brief but
  103. specific — not "found a bug" but "the formula translator was re-parsing
  104. identical ASTs 415K times because the cache key included per-cell context,
  105. making the cache effectively useless."]
  106. ## Open Questions
  107. [What remains uncertain. Where the current theory might break. What evidence
  108. would change the approach.]
  109. ```
  110. ## Tone
  111. Write as a thoughtful engineer explaining their mental model to a peer.
  112. Direct, specific, no filler. Use concrete examples from the codebase.
  113. Avoid hedging language — state the theory clearly, and separately note
  114. where confidence is low.
  115. ## Practical Rules
  116. - One THEORY.MD per repo, at repo root (`THEORY.MD`).
  117. - Maximum ~200 lines. If longer, tighten the prose.
  118. - Rewrite holistically, never append.
  119. - Update when theory changes, not when code changes.
  120. - Stay active for the whole session once activated.
  121. - Prefer frequent concise rewrites over infrequent large rewrites.
  122. - If the session remains trivial (one-liner fix, config change), stay active
  123. but no-op the document creation/update requirement.
  124. - If multiple workstreams are active, the theory should cover the primary
  125. one with brief notes on how others connect, not try to be comprehensive
  126. about everything.
README.md · README · 67 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Theorist
  2. Maintain a continuously updated operating theory for ongoing engineering work.
  3. `theorist` is an agent skill (Codex and Claude compatible) that keeps a per-repo narrative document at
  4. `THEORY.MD` (repo root). The document explains the problem thesis, the current
  5. system model, why the strategy is shaped the way it is, and where uncertainty
  6. still exists.
  7. It is intentionally not a task plan, changelog, or status report.
  8. ## Install
  9. Use a skills directory for your client and clone into it:
  10. ```bash
  11. SKILLS_DIR="${CODEX_SKILLS_DIR:-${CLAUDE_SKILLS_DIR:-$HOME/.codex/skills}}"
  12. mkdir -p "$SKILLS_DIR"
  13. git clone https://github.com/blader/theorist.git "$SKILLS_DIR/theorist"
  14. ```
  15. If you already have the repo checked out, copy just the skill file:
  16. ```bash
  17. mkdir -p "$SKILLS_DIR/theorist"
  18. cp SKILL.md "$SKILLS_DIR/theorist/"
  19. ```
  20. ## Usage
  21. Invoke it using your client's skill command.
  22. Or ask naturally:
  23. - "Keep the operating theory updated while you work."
  24. - "Rewrite the theory doc based on what we just learned."
  25. - "What changed in our theory after this debugging pivot?"
  26. ## What it enforces
  27. - One theory doc per repo at `THEORY.MD` (repo root)
  28. - Always-on activation in every session
  29. - Sticky activation: once active, it stays active for the full session
  30. - Holistic rewrites (not appended logs)
  31. - Clear separation between:
  32. - problem thesis,
  33. - operating theory,
  34. - strategy,
  35. - key discoveries/pivots,
  36. - open questions.
  37. - Frequent in-session updates as learnings arrive (especially after
  38. investigate/implement/verify loops and verification outcomes).
  39. - Updates when understanding changes, not when code churn happens.
  40. ## Why this helps
  41. Most agent workflows optimize for local task completion. `theorist` adds a
  42. lightweight strategic memory layer so future decisions remain coherent with the
  43. latest mental model of the system.
  44. ## Files
  45. - `SKILL.md`: canonical skill behavior and writing standard
  46. ## License
  47. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.