Every repo that uses okl keeps a thesis: set it up, keep it true, let it evolve

Open
  • Is something wrong?
#321 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
15/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Active
Tech stack
python
Domain
developer-experience, documentation

Research direction

This is a design issue, and the questions under 'Decide after step one' are still open, so settle those with the maintainer before writing code. Step one is to draft docs/THESIS.md for okl itself, listing every promise in the README, docs and site with its status and evidence, and to correct copy that overclaims, such as the 'each entry is proven by a check' line. Done when every promise is listed with evidence and a test fails when the headline or a figure moves without the thesis.

Written by the indexing model from the issue text.

Description

enhancement

Part of #317. Builds on #238 (a pinned lesson), #319 (figures held to receipts) and #314 (doc claims).

Why. okl keeps lessons true to the code. A repo's overarching goal drifts the same way, and nothing watches it. On okl itself (2026-11-01), an inventory of the README, the other docs and the maintainer's site found about 90 distinct promises about what okl does. The thesis page tracked about 10 of them. Several docs promised more than the evidence shows: "each entry is proven by a check", when 71 of the 155 lessons recorded here have one; and "so they cannot drift silently", when drift caught 14 of 36 judge-confirmed breaks (REPORT §4af). The goal had spread across copy, and no single page held it.

What a thesis is. One page per repo, docs/THESIS.md. It is the primary record of the project's scope: other copy describes from it, and a wider direction is added beside existing promises, never in their place. It holds:

  • the claim, in one line;
  • the problem it answers, and the principles that hold throughout;
  • what the project holds, what it watches, and what it leaves to other tools;
  • every promise it makes, each with its status (built, partly, in review, direction) and its evidence;
  • a measured baseline;
  • a history of how the claim changed, and why.

Proposal. Every repo that uses okl keeps one, in four parts:

  1. Set up. A guided step, offered by okl init, as a command and an agent skill. It drafts a starter thesis from what the repo already has: the README's headline, its docs, its ADRs, its CI checks and its lessons. It asks the person to confirm the claim and what is in scope, writes the page, links each promise to the lesson or check behind it, and pins the claim (#238) so every session starts from it.
  2. Kept true. Each promise is linked to its evidence. okl drift and okl recap list promises with no evidence, and evidence that has moved. A figure test like #319 fails when a number on the page leaves its receipt.
  3. Evolves. As the work goes on, the session-end question and okl recap suggest changes to the scope: a new doc, command or feature that no promise covers; copy that promises something the thesis does not; a promise whose evidence went stale. The agent proposes, the person decides, and the history records why.
  4. The principles still hold. okl notices mechanically and calls no generative model in its own loop. Reading prose for promises is the agent's work in the session, from a skill okl ships. Every change is deliberate and visible.

Step one: do it on okl.

  • docs/THESIS.md becomes the primary record of okl's scope, listing every promise the README, the docs and the site make, with status and evidence. Drafted after #312 merges.
  • The claim is pinned (#238), or until then sits in CLAUDE.md.
  • Each promise is linked to the lesson or receipt that backs it.
  • #319's figure test lands.
  • What had to be done by hand, and what could be mechanical, is written down.

Decide after step one. Whether a thesis is its own record type or a pinned Decision plus a page; how a promise links to its evidence (an edge type, or the page's table); what okl init writes; and how the agent is told to guide the person through it.

Done when (step one).

  • okl's thesis lists every promise its README, docs and site make, each with a status and evidence.
  • Copy that promises more than the evidence is corrected, or the thesis says why it stands.
  • A test fails when the headline or a figure moves without the thesis.
Dominant language
Python
Stars
1
Forks
1
Avg merge
5h 45m
Merged PRs (30d)
118

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from emeraldleaf/okl

All issues in emeraldleaf/okl

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.