Repository navigation
[agent-experience] Route doc changes by kind of fact in the AGENTS.md template - #21
Merged
Merged
Conversation
… template Fold back item 3 of the Oct 13 2026 improve-mode field report: the docs' contract has to live in the repo, because the templates' guidance comments are deleted before commit and most later sessions run without this skill. - docs-structure.md, Design docs lifecycle, owns the amendment rule: the delta and the decision, a line or two; build facts (progress, measurements, verification output, review decisions) go to the effort's exec plan; an index entry is the link and its trust label, nothing else. - agents-md.md: definition of done couplings into docs/ route by kind of fact and name what the destination does not take; a pointer line carries the target's contract (holds, stays out, size where one is set) and never points outside the repo, at a skill installed in the agent included. - AGENTS.template.md: the definition of done routes all five doc kinds (ARCHITECTURE.md entry, spec, design amendment, ADR, exec plan); the ADR line is propose-and-confirm, since what counts as an ADR is the user's call. Pointer lines are pure contracts. - docs-structure.md, ADRs: the agent proposes an ADR and only the user's confirmation creates it; agents left to themselves file too many. - design-doc-template.md: the Amendments comment points at the owner. - website/agent-experience.md: one sentence on where the contract lives. - AGENTS.md: sharpen the fold-back rules after this change's first draft stated the same list in four files and routed two of the five doc kinds: a pointer names file and section, not list position, and carries at most the rule's one-line statement; the example lives in the owner line only; a rule is applied to every instance the skill already covers. Held, with reasons, so the next fold-back does not re-apply them: - Item 1, second half (a design doc ahead of a multi-session build triggers an exec plan): the exec-plan rubric needs its own pass. - Item 2 (body rewritten to as-built; Context, Provenance limits): the lifecycle sentence and the template sections need re-reading as a whole; only the index-entry clause is folded. - Item 3's design-docs index template: a new asset beyond this fold-back's scope, and the trust-label home is still undecided (PR #14 follow-up). - Items 4, 5, 8 (check_docs length sensor, quantifier attribution, restatement cross-check): script changes with tests, a separate change. - Item 6 (diff-scoped improve mode): changes how users invoke the skill, needs the usage guide and evals in the same change. - Items 7 (login-shell execution) and 9 (exec-plan move updates inbound links): separate changes. Verified: check_docs passes with 0 errors, website build passes, evals.json reviewed and unchanged (no assertion names the old wording). Co-Authored-By: Claude Fable 5.1 <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
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.
Observation from working with agent-experience: agents tend to grow the agent-facing docs in an uncontrolled way. This change aims to mitigate this problem, but users need to keep an eye on this so the agent experience layer of a repo stays maintainable.