docs: say when an issue gets opened, and point agents at it - #240
Merged
Merged
Conversation
The constitution said where an issue goes and what it is not. It did not say when to open one, which is the question that actually comes up: something turns up while you are doing something else, and widening the change buries the fix in a diff about something unrelated while saying nothing loses it. Adds that threshold, and the obligation to carry the evidence and the command that reproduces it, which the Verification principle already requires of a page. Also drops the last of the spec-kit vocabulary from the principle. It spoke of a specification and a task list as separate records; the page is the record now. CONTRIBUTING.md gains the practical version, including which repository an issue belongs to. AGENTS.md gains a pointer, because widening the change is the part agents get wrong. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c
|
Thank you for contributing to this project! 😊🕹️ |
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.
CONSTITUTION.mdalready had a## Trackingprinciple covering where an issue goes and what it is not. Two gaps.It did not say when to open one
That is the question that actually comes up: something turns up while you are doing something else. Widening the change buries the fix in a diff about something unrelated. Saying nothing loses it. Neither is tracking.
Plus the obligation to carry the evidence and the command that reproduces it, which the Verification principle already requires of a page and for the same reason.
It still spoke spec-kit
There is no specification and no task list. The page is the record now, so an issue is closed by the pull request that makes its page true.
The practical version
CONTRIBUTING.mdgains an## Issuessection, mainly to settle which repository an issue belongs to. A finding about osapi's code is an osapi issue, because that is where the person who fixes it is looking. An issue here is for the design record itself: a page that is wrong, a subject with no page, a rule stated in two places.AGENTS.mdgains a short pointer. Widening the change is the part agents get wrong, so that is what it names.Worked examples from today
Three findings from auditing the provider contract, all filed against osapi rather than here, each carrying its reproduce command:
scheduleis the only domain with no integration testssysctldecides idempotency from its own recordjust testpasses.🤖 Generated with Claude Code
https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c