Skip to content

docs(quality): add the perpetual-diff criterion - #78

Merged
robinbowes merged 1 commit into
mainfrom
docs/perpetual-diff-criterion
Aug 25, 2026
Merged

docs(quality): add the perpetual-diff criterion#78
robinbowes merged 1 commit into
mainfrom
docs/perpetual-diff-criterion

Conversation

@robinbowes

Copy link
Copy Markdown
Contributor

New criterion

Added under Plan and apply discipline:

A diff that reappears after being applied is a provider Read/Update
asymmetry, not drift. Read the provider source for that field before applying
it a second time — a field Update never sends, on a resource whose Update
ends by calling Read, can never converge. Applying repeatedly is the failure
mode: it looks like progress and changes nothing. Fix it by making config match
reality, by ignore_changes, or by changing the underlying object — not by
re-applying.

Written from python-template (#77). Its template block diffed on every plan.
Applying the removal was tested and the diff returned on the next plan: provider
v6.13.0 resourceGithubRepositoryRead sets template from the API
unconditionally, resourceGithubRepositoryUpdate never sends it, and Update
ends by calling Read.

Dated

Three categories triggered on 2026-08-25 and now say so, each keeping its
previous entry as Last triggered (prior):

  • Plan and apply discipline — the read-the-plan criterion also carried the
    repo swap: the plan showed no state rm was needed, contrary to what had been
    planned for it.
  • Post-apply outcome verification — the swap was confirmed against the
    GitHub API, not by re-reading the config that produced it.
  • Decision records — two records logged, and CLAUDE.md plus the
    default_branch_ruleset_non_fork_bypass_actors description updated in the
    same PR that changed the query they describe.

Note on the diff

Several Last triggered paragraphs are reflowed to keep the file at 80 columns.
Verified no prose was lost: comparing word multisets before and after gives 0
words removed, 247 added (the new criterion plus the new entries).

🤖 Generated with Claude Code

A diff that reappears after being applied is a provider Read/Update
asymmetry, not drift. Applying it repeatedly looks like progress and
changes nothing, which is what happened to python-template's template
block before the provider source was read.
Also dates the three categories that triggered on 2026-08-25: plan and
apply discipline, post-apply outcome verification, and decision records.
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

@yo61-lastlightyo61-lastlightBot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This documentation-only PR adds the perpetual-diff criterion and refreshes the relevant last-triggered notes. I found no blocking correctness issues in the changed guidance.

@robinbowes
robinbowes merged commit b61fdef into mainAug 25, 2026
2 checks passed
@robinbowes
robinbowes deleted the docs/perpetual-diff-criterion branch August 25, 2026 18:50
Sign up for freeto 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

@robinbowes