johnandersen777.bsky.social/knotless

Switch repository

Loading…

---
name: docs
description: Write, rewrite or check a page of knotless's docs (docs/, README.md) against the code. Use when a change alters what a doc page says, when asked to write or rewrite a page, or to audit pages for drift. Facts come from the code first; the page is then written from the reader's questions, never by editing old prose.
---

# Writing knotless's docs

Rewriting a page by editing it keeps its shape and its mistakes. These
pages are written from facts instead: gather what the code does, decide
what the reader asks, and write the page fresh with no old prose in view.
Then check it against the facts.

`docs/` is a small wiki, one kind of page per directory:

- `docs/design/`: why it works the way it does. One mechanism per page,
  each explained as the answer to a problem.
- `docs/guide/`: how to do one thing, in steps.
- `docs/reference/`: every flag, method, field and message, to look up.

The map from code to pages is in AGENTS.md, under Docs.

## Which job

- A small change to what a page says (a new flag, a changed limit): edit
  the page and the reference that lists it, in the pull that makes the
  change. Check the edit against the code it describes. Steps 1 and 4
  below are enough.
- A page to write or rewrite: all four steps.
- An audit (are these pages still true?): steps 1 and 4 for each page,
  then fix what is wrong, or file an issue when the code is what's wrong.
  The `docs-audit` workflow does steps 1 and 4 on the runner when the
  owner asks (`knotless run rerun <repo> --ref refs/heads/main --workflow
  docs-audit`), one session per page, and reports at the end of its log;
  it costs model usage, so ask first. Verify each finding against the
  code before acting on it.

## 1. Facts

Have an agent read the code the page covers, and the page as it stands,
and write a fact inventory to a scratch file. Each fact is one line,
tagged:

- `[code]` read in the code (name the file and function)
- `[doc]` said by a page, not found in the code
- `[both]`
- `[DOC WRONG]` a page says something the code contradicts: give both

A section headed Quirks lists what looks like a bug, with file and line.
Those are filed as issues (`knotless issue create`), not written up as design.
Drop `[doc]` facts the code does not bear out.

## 2. Context

Write a short context file for the writer:

- The reader: who they are, what they already know (git, CI, roughly what
  atproto is), and why they came to this page.
- knotless in three lines (see context.md beside this file).
- A glossary of only the atproto and knotless terms the facts use.
- The pages it may link to, by path.
- The questions the page answers, in the order a reader asks them. The
  lists for the design pages are in questions.md beside this file; start
  from those and add what the facts raise.

## 3. Write

Give a fresh agent only the facts and the context, and tell it not to
read `docs/`, `README.md` or `AGENTS.md`. It may read code to settle a
doubt, and says so. The brief, with the style rules, is writer.md beside
this file.

It reports the facts it left off and where each belongs. Place those in
the reference pages and guides yourself (or with another agent), checking
each against the code as you go: details belong there, not on a design
page.

## 4. Check

- Every fact on the page against the inventory, and any doubt against the
  code. Agents drop true facts no source stated, and keep false ones a
  page did: read the diff of what was there before.
- Pages that state the same thing agree. `security.md` and the overview
  draw on the others, so check them last.
- `just docs`: links, anchors, and every Mermaid block draws with Pele
  (`npm ci` in `web/` first). The `docs` check runs it on the pull.
- Read the page once as its reader would, top to bottom.