From a29b0e0b3133de3764dfebdcf095d045fa0b91df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Fri, 14 Aug 2026 23:24:02 -0700 Subject: [PATCH 1/2] docs: say what to do when you find something MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The operating model describes how to run a change once you have decided to make one. It says nothing about the moment before that — noticing a problem — which is where the process actually gets skipped. Three times in this standardization the work landed before the requirement: LICENSE years changed across six repositories, then the requirement corrected; AI_POLICY wording fixed, then the specification updated; stray tracked files removed, then the rule written. Each time the corpus was made to describe what had already happened rather than what was agreed. Add the decision that was missing: does a requirement already cover this? If yes, it is compliance work and the pull request cites it. If no, propose first. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 11 +++++++++++ CONTRIBUTING.md | 20 ++++++++++++++++++++ 2 files changed, 31 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 2e0d7d1..436332e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,6 +13,17 @@ Follow it rather than improvising: propose, merge, apply, archive — each step its own pull request, except documentation-only changes where propose and archive belong in one. +## When you find something + +Before editing any repository, answer: **which requirement authorizes this?** + +If a requirement covers it, the fix is compliance work — cite the requirement in +the pull request. If none does, propose the change first. Do not fix it and +write the requirement afterwards; that produces a corpus that describes what +already happened rather than what was agreed. + +See @CONTRIBUTING.md under "When you find something". + ## Planning boundary `/opsx:propose` produces planning artifacts and then stops. Do not edit code in diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 49ec1e4..883215b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -189,6 +189,26 @@ the spec while implementing, update the change rather than quietly building something else, then `/opsx:sync` so the corpus reflects what was actually built. +## When you find something + +Most work starts by noticing a problem rather than by deciding to write a +change. What you do next depends on one question: + +**Does a requirement already cover it?** + +- **Yes** — fixing it is compliance work. Open an ordinary pull request against + the repository, and cite the requirement it satisfies. +- **No** — propose first. The fix is the second step, not the first. + +The temptation is to fix it immediately, because fixing feels like progress and +the change process feels like overhead. That is exactly how the corpus falls +behind reality: the work lands, the requirement is written afterwards to +describe what was already done, and nothing was ever actually agreed. + +If a fix is urgent, do it — then open the change and say in it that the work +preceded the requirement. Skipping the change entirely is what leaves the next +person with a rule that exists only in someone's memory. + ## Running a change `main` is protected, so each step below is its own pull request. From d10a1ee3b6e971d387b9b1709aca8c67f96df96f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Fri, 14 Aug 2026 23:28:43 -0700 Subject: [PATCH 2/2] docs: say to read the corpus before starting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Nothing instructed anyone to read openspec/specs/. AGENTS.md said to read CONTRIBUTING, and config.yaml before writing artifacts, so every instruction could be followed without ever opening the corpus. That is what made "does a requirement already cover it?" unanswerable in practice — the question was there, the instruction to go look was not. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 9 +++++++++ CONTRIBUTING.md | 9 +++++++++ 2 files changed, 18 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 436332e..5cccfba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,6 +13,15 @@ Follow it rather than improvising: propose, merge, apply, archive — each step its own pull request, except documentation-only changes where propose and archive belong in one. +## Read the corpus first + +Before starting work in any repository, read `openspec/specs/` for the +capabilities that bind it. `openspec/specs/repo-standards/` binds every +repository; the rest bind by type, recorded in the classification. + +Requirements are not advice. A repository that does not satisfy one is +non-conformant, and work that leaves it that way is unfinished. + ## When you find something Before editing any repository, answer: **which requirement authorizes this?** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 883215b..8c8132c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -189,6 +189,15 @@ the spec while implementing, update the change rather than quietly building something else, then `/opsx:sync` so the corpus reflects what was actually built. +## Read the corpus first + +`openspec/specs/` is the standing answer to what is true about osapi-io. Read +the capabilities that bind the repository you are working in before you start — +`repo-standards` binds every repository, and the classification records which +others apply by type. + +This is what makes the next question answerable. + ## When you find something Most work starts by noticing a problem rather than by deciding to write a