Repository navigation
Rewrite the docs for human readers and move agent rules to AGENTS.md - #130
Merged
Merged
Conversation
The README had grown to 714 lines mixing user docs, the spec pitch, and refresh-pipeline internals, and much of the prose read as machine written. It is now the user path (quick start, commands, Action, config, how retirement dates work, the bot, data sources, limits), with reference material split into docs/CONFIGURATION.md, docs/BOT.md, docs/RECEIPTS.md, and docs/FEEDS.md, and parser behaviour in refresh/README.md. docs/CONTEXT.md, docs/DESIGN_BOT.md, and docs/PRODUCT_PLAN.md are removed. Their settled design decisions now live in CONTRIBUTING.md, the current bot architecture in docs/BOT.md, and agent-only rules in AGENTS.md, which CLAUDE.md imports. Two fact-check passes against the code corrected claims that were wrong before this rewrite too: waiver expiry does not undo a human dismissal, earliest dates can fail CI, the bot opens PRs without a configured eval, cloud and gateway references open issues under scope direct, routes do not make a routed alias fail under scope direct, the refresh never drops models, and amazon.json is carried forward. Stale Azure and Bedrock dates and the demo GIF are refreshed. SPEC.md and SECURITY.md change wording only, not requirements or scope. The two tests that read README text now read docs/BOT.md and docs/RECEIPTS.md. Written by Claude; fact-checked and prose-reviewed by Opus subagents.
#125 escapes text output and stderr, JSON printed to logs, Markdown alerts, and bot-written bodies, in addition to the annotations and badge JSON the scope already listed.
thossullivan
force-pushed
the
docs/human-pass
branch
from
October 24, 2026 02:09
3744150 to
c8dabeb
Compare
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.
Summary
README.mdis down from 714 to about 300 lines and covers the user path: quick start, commands, the Action, configuration, how retirement dates work, the bot, data sources, and limits.docs/CONFIGURATION.md,docs/BOT.md,docs/RECEIPTS.md, anddocs/FEEDS.md. Parser behavior moves torefresh/README.md.docs/CONTEXT.md,docs/DESIGN_BOT.md, anddocs/PRODUCT_PLAN.mdare removed. Settled decisions now live inCONTRIBUTING.md, and agent-only rules inAGENTS.md, whichCLAUDE.mdimports.SPEC.mdgains a terms section and a feed-field table. Its requirements are unchanged.SECURITY.mdis reworded. Its scope is unchanged.Accuracy
Two fact-check passes against the code fixed claims that were wrong before this rewrite too:
earliestdates can fail CI.scope: direct.scope: direct.amazon.jsonis carried forward rather than generated.Tests
The two tests that read README text now read
docs/BOT.mdanddocs/RECEIPTS.md.npm testpasses.Follow-up
PRs #125 to #129 change behavior that
refresh/README.md,docs/FEEDS.md, andSECURITY.mddescribe. Once they merge, this branch gets one more commit to match.🤖 Generated with Claude Code