Add scoped Labyricorn authoring guidance

2026-08-11 22:48:09 -07:00
parent feea2e67de
commit a4ad2ad10a
3 changed files with 160 additions and 0 deletions
@@ -0,0 +1,54 @@
+# 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.