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.