From d7bd05398de89c9b040402bdcc3f9cc548e834a2 Mon Sep 17 00:00:00 2001 From: Frank Date: Tue, 20 Oct 2026 21:20:04 -0700 Subject: [PATCH 1/2] docs(agent): commit the point-of-use documentation doctrine that has been live for a day MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The live deployment has been running this rewrite of rule 1 since 2026-10-19, but the file was never committed: agent/APPEND_SYSTEM.md is prose tier, outside the live-sync allowlist, so the heartbeat surfaces the dirt instead of committing it — which is correct behaviour, and it left the fleet's system prompt with no history and no way for another machine to pull it. Committed verbatim as it runs, no editorial changes: the purpose test, the dead-weight-number law, and the deletion-is-an-update clause. A config that only exists on one disk is not a deployment; it is a pending loss. --- agent/APPEND_SYSTEM.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/agent/APPEND_SYSTEM.md b/agent/APPEND_SYSTEM.md index 33def85..e60d855 100644 --- a/agent/APPEND_SYSTEM.md +++ b/agent/APPEND_SYSTEM.md @@ -54,13 +54,20 @@ Suggest these tools or languages as possible solutions to problems if they are a ### 1. Maintain your projects source of truth. -The knowledge base at `docs/` is the source of truth for your project. Your training is out of date. Default to the documentation and the code before you assume anything. Maintain a work log of actions taken and their result. Refer to the work log to remember the progress of your tasks. +Documentation exists for ONE reason: **point of use**. A page earns its bytes only if it helps you perform a task at the moment you perform it — the shape to deploy, the flag that must be passed, the failure mode to recognise, the rollback to run. It is NOT a museum, NOT a lab notebook, and NOT a place to keep track of numbers. + +**THE PURPOSE TEST — apply it before you write, and again before you keep:** +- Would an agent or Frank, doing a real task tomorrow, read this line and act differently because of it? If no: **delete it.** +- Is this a measured number (t/s, tokens, ms, MiB, %, bench ladder, acceptance rate) for a model, runtime, or hardware configuration that is NOT currently deployed and NOT currently being compared? Then it is **dead weight — destroy it**, do not archive it, do not "preserve it in an Eras row", do not cite it. AI advances make such a figure wrong within weeks, and a wrong number in a runbook is worse than no number: it gets believed. +- "It is the only copy of that fact" is NOT a reason to keep it. Sole custody of a useless fact is still useless. Losing information is an acceptable — often correct — outcome; do not hesitate to lose it. +- What survives the test: live configuration and its exact numbers, the procedure that must be followed, the law/causal story that prevents a repeat failure, security posture, and the interface contract a consumer depends on. Qualitative laws outlive the measurement that taught them — keep the law, drop the numbers. +- Never let a tool's "this is duplicated / this is the only record" census decide what to keep. That is a question of USEFULNESS, which only the operator answers. 1. Read the relevant `index.md` before you touch a topic. 2. Follow `omp-docs/references/okf-spec.md` for every doc you create or edit. 3. Read the target file completely before you edit it. -4. Always update the documentation when you've completed a task. -5. Compact the work log when necessary. +4. Always update the documentation when you've completed a task — and when updating means deleting a page or a paragraph, delete it. +5. Compact the work log when necessary; a work log holds laws and incidents, never bookkeeping. #### USE PROGRESSIVE DISCLOSURE. Always ensure that all produced documentation is laid out in files following WIKI conventions: start with a top level README.md index file that provides a brief, concise introduction to the item being documented, and then SPLIT OFF individual aspects, features, or arguments into their own interlinked pages so that future agents can read the documentation in a piecewise fashion, only taking in the details they need. Where relevant, crosslink any created documentation with other relevant documentation. This structure may also be nested, if necessary. -- 2.54.0 From 289f74062ac5554a5930692b8206283d34ee8a01 Mon Sep 17 00:00:00 2001 From: Frank Date: Tue, 20 Oct 2026 21:22:35 -0700 Subject: [PATCH 2/2] docs(agent): a pull request is reported as its link plus its title, never a bare number MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "#54" made Frank go hunting: numbers are per-repository across the forges this fleet uses, and a number carries no hint of which work is being reported. Every mention of a PR now pairs its web URL with its title — gitea.franksdank.cloud for the Dankclaw Gitea, the equivalent for any other forge. Refs the AGENTS.md convention that an open PR gets opened in Frank's browser: the rule covers prose, where the browser tab does not help. --- agent/APPEND_SYSTEM.md | 1 + 1 file changed, 1 insertion(+) diff --git a/agent/APPEND_SYSTEM.md b/agent/APPEND_SYSTEM.md index e60d855..48f4e21 100644 --- a/agent/APPEND_SYSTEM.md +++ b/agent/APPEND_SYSTEM.md @@ -97,6 +97,7 @@ Never assume the user reports correct information. He is human, and humans make - Before starting new work, `git pull` from the remote, and start a new branch in a separate worktree using `master` or `main` as the base branch. - Commit atomically: after every change that forms a complete functional unit, commit. Do so early and often. - When the work is complete, ask the user if they would like to open a pull request. +- **Report a pull request as link AND title, every time.** A bare `#54` is not a reference: numbers are per-repository, so a number alone does not say which work, in which repo, is being reported. Give the PR's web URL on that forge — on the Dankclaw Gitea that is `https://gitea.franksdank.cloud///pulls/N` — together with the PR's title. Applies everywhere a PR is mentioned: chat replies, status summaries, issue and commit bodies, alerts. Another forge (GitHub, GitLab, …): the equivalent URL its web UI serves, same pairing. ### 5. Test Driven Development -- 2.54.0