Skip to content

docs: cut restated rules and inferable reasons from merged instructions - #461

Merged
davidvornholt merged 1 commit into
mainfrom
docs/cut-merged-redundancy
Oct 22, 2026
Merged

davidvornholt merged 1 commit into
mainfrom
docs/cut-merged-redundancy

Conversation

@davidvornholt

Copy link
Copy Markdown
Owner

Before. Merged skills and instructions still contained text an agent loading AGENTS.md doesn't need. The issues skill pointed to the AGENTS.md change policy, and the prs skill restated its "state each fact once" rule. Several reasons explained what a capable model infers anyway, and the screenshots skill carried a history anecdote. Every agent pays for those words on every read.

Now. The rules are unchanged, and only the restatements, inferable reasons, and history are gone.

Implementation

Cuts, each separable:

  • issues: "present the choice as the change policy in AGENTS.md describes". Every agent already loads AGENTS.md.
  • prs: "don't repeat what another section says", which restates AGENTS.md. Also "because running it on every intermediate push was costly" and the sentence about the decider relying on the check lines. The verification line keeps its substance: what ran, how much passed, partial runs and failures.
  • screenshots-in-prs: the history of improvised hosting, and why a matched pair shows the change's size.
  • AGENTS.md: "because those choices are the user's and expensive to reverse", which restates "costly, durable".
  • AGENTS.local.md: "Revisit this only if that bootstrap premise changes."
  • docs/operations.md: "because an unpushed ref does not exist remotely".

Kept, because they're cheap to state and costly to rediscover or get wrong:

  • the gh pr ready and gh pr ready --undo commands;
  • why a suggested approach in an issue gets treated as settled;
  • why "the feature didn't exist" gives the decider nothing to weigh;
  • that published screenshots are public and kept indefinitely.

frontend-design is unchanged. It's Anthropic's skill, vendored with its license.

Words: prs 477 → 445, screenshots-in-prs 241 → 212, issues 177 → 166, AGENTS.md 522 → 512, AGENTS.local.md 269 → 261, docs/operations.md 353 → 345.

Verification

Completed checks

  • bun run check passed: structure, source text, Dependabot, and GitHub settings checks, then 7 of 7 Turbo tasks.
  • git diff --check: clean.

@davidvornholt
davidvornholt force-pushed the docs/cut-merged-redundancy branch from de4d926 to a102999 Compare October 22, 2026 18:18
@davidvornholt
davidvornholt marked this pull request as ready for review October 22, 2026 18:18
@davidvornholt
davidvornholt marked this pull request as draft October 22, 2026 18:23
@davidvornholt
davidvornholt marked this pull request as ready for review October 22, 2026 18:23
@davidvornholt
davidvornholt merged commit 670c27d into main Oct 22, 2026
17 checks passed
@davidvornholt
davidvornholt deleted the docs/cut-merged-redundancy branch October 22, 2026 18:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant