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

Aperta
  • Qualcosa non va?
#321 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
15/100
Tipo di issue
Funzionalità
Chiarezza
Da chiarire
Stato di attività
Attiva
Stack tecnologico
python
Ambito
developer-experience, documentation

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.
Lingua principale
Python
Stelle
1
Fork
1
Merge medio
6h 1m
PR unite (30g)
121

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di emeraldleaf/okl

Tutte le issue di emeraldleaf/okl

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.