docs: say what to do when you find something - #24
Merged
Conversation
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) <noreply@anthropic.com>
|
Thank you for contributing to this project! 😊🕹️ |
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) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The operating model covers how to run a change once you have decided to make
one. It says nothing about the moment before — noticing a problem — which is
where the process actually gets skipped.
This happened three times in this standardization
AI_POLICY.mdwordingEach time the corpus was made to describe what had already happened rather than
what was agreed. Each time it took someone asking "was that recorded?" for the
spec to catch up.
The missing decision
Does a requirement already cover it?
With the honest caveat that urgent fixes happen: do it, then open the change
and say 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.
Both audiences
CONTRIBUTING.mdgets the reasoning;AGENTS.mdgets the operative form —before editing any repository, answer: which requirement authorizes this? —
and points at CONTRIBUTING rather than restating it.
🤖 Generated with Claude Code