# Instructions for the Thinkloom development log

These instructions supplement `.labyricorn/AGENTS.md` and apply to the
`devlog/` directory.

## Index and entry structure

- Keep the devlog index at `devlog/contents.lr` using `_model: devlog`.
- Store each published entry at `devlog/<stable-slug>/contents.lr` using
  `_model: devlog-entry`.
- Use a lowercase hyphenated directory name that describes the milestone. The
  directory name becomes part of the public URL and must remain stable.
- Every entry must include `schema_version`, `title`, `date`, `author`,
  `summary`, `tags`, `source_commit`, and `body`.
- Set `source_commit` to the full 40-character commit ID most directly
  associated with the entry. Confirm that it resolves in this repository.
- Use the commit's actual calendar date for retrospective entries. Do not use
  the date on which the devlog prose was written.

## Editorial guidance

- Base retrospective entries on verifiable repository history, existing project
  documents, and implemented behavior.
- Do not invent motivations, conversations, results, release status, user
  feedback, or completion claims.
- A devlog should explain the milestone, why it mattered, and what changed. It
  should not merely expand a commit message or enumerate every changed file.
- Distinguish a design or schema contract from a completed runtime
  implementation.
- Keep one main milestone per entry. Link to the relevant canonical commit using
  the Gitea HTTPS URL.
- Write summaries that work in chronological listings without requiring the
  reader to open the entry.
- Use focused tags consistently; avoid creating capitalization or spelling
  variants of an existing tag without a reason.

## Chronology and lifecycle

- The Labyricorn site orders entries by `date` and provides links back to the
  project and to older/newer entries. Do not add manual next/previous links.
- Multiple entries may share a date; ordering ties should be resolved by the
  importer from source history rather than invented timestamps in prose.
- Do not rewrite old entries merely because the implementation later changed.
  Add a new entry or a clearly labelled correction when historical context is
  needed.
- Do not delete or rename a published entry without explicit approval and a
  redirect or archival decision for its existing URL.

## Review requirements

- Verify the entry date and `source_commit` against `git log`.
- Check that the source-commit link targets the same full commit ID.
- Check prose against the referenced commit and current documentation.
- Parse the record with Lektor and run `git diff --check` before committing.