From b5168e657e52003bb24357cec8f5902cdd58ee03 Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 29 Jul 2026 17:46:22 +0200 Subject: [PATCH] docs: broaden the verify-before-acting rule in AGENTS.md The rule named only claims inherited from pull requests and issues, so it did not cover the two sources that actually produced wrong statements while writing these files: a stale project memory, and a conclusion drawn earlier in the same session. Both were copied into a committed file before being caught. Also record that running a documented command only proves it executes -- the output filter in CLAUDE.md ran fine while matching 2968 of 5293 log lines -- and that existing docs should be read before new ones are written. --- AGENTS.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8d3845b36..53e289c0b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,6 +28,10 @@ wrong or the expected list needs updating — decide which, do not just update t Modules are listed in `settings.gradle.kts`; only `:testng` is published, as a shaded jar merging the others. `docs/BUILD_SYSTEM.md` describes the structure. +Before writing documentation, read what is already in `docs/` and `.github/`. Most build topics are +covered there; a second copy drifts from the first, and this file was itself written as a fifth copy +before being cut back to links. + Two things that are not documented elsewhere and cost tool calls to discover: - Per-project build files are named `/-build.gradle.kts`, not `build.gradle.kts`. @@ -101,10 +105,14 @@ version heading. ## Working style -- **Verify claims before acting on them.** A statement inherited from a pull request description, an - issue or a comment is not evidence. Checking a release date or a changelog costs a minute; acting - on a wrong premise costs hours. This has already caused one full migration to be written and - reverted. +- **Verify claims before acting on them** — including your own. A pull request description, an issue + comment, a memory or a conclusion from an earlier session are all hearsay until re-checked against + whatever settles them: the build for anything about this repository, the registry or upstream + release notes for anything about a dependency. A release date costs a minute to check; acting on a + wrong premise costs hours. This has already caused one full migration to be written and reverted, + and one obsolete memory to be copied into a committed file. +- Running a documented command proves it executes, not that it does what the text claims. If the + text promises an effect — filtering, failing, producing a value — measure that effect. - Report what you actually observed. If a run was flaky, say so and show both runs. - When an upgrade is refused, record the error that refused it, so the next person does not retry it blind.