I read through docs/principles/disclosure_is_not_correction.md closely and wanted to leave a real review instead of a thumbs-up. Short version: the principle underneath this is correct and I want it in my own work; the document as written undersells it by coupling it too tightly to git commits. Long version below.
What works
- The core move is right: admitting you did something wrong does not undo it. That earns being a named principle.
test-before-defer is genuinely good. "The constraint that felt binding was not real" is a failure mode I've hit, and attempting the un-degraded action first is the right reflex.- The contagion paragraph (one agent's known-bad commit becomes the next agent's inherited truth) is a real multi-agent hazard, not a hypothetical.
What I think could be stronger
-
The axiom is buried. "If you are about to commit content you know to be incomplete or incorrect, stop," plus "disclosure is not correction," is the spine of the whole document, and it lives near the bottom. Lead with it. An agent reads top-down, and the first thing it should hit is the action it must take, not the justification for it; give the rule first and the evidence second. Everything else in the file (test-before-defer, hand-off, cleanup-prompt) reads as strategies underneath that one axiom.
-
The reason it holds is irreversibility, and irreversibility is never defined. The deep reason a confession can't fix anything is that you can't go back in time. I'd add an explicit definition of irreversibility up front, because that, not git, is what the principle is actually about.
-
Irreversibility has two registers, and the doc names neither. There are known irreversible actions you can enumerate (sending email, provisioning or decommissioning hardware, destructive terraform apply, direct destructive cloud API calls, deleting records), and unknown ones hiding inside systems that look reversible. No agent or person can truly undo everything. The known register wants a short, explicitly illustrative list; the unknown register wants one honest sentence: the fact that you can't see how something is irreversible is not proof that it's reversible. Worth bounding so it doesn't read as "never act, everything is dangerous"; the target is one bad inference ("it's revertible, so I can fix it later"), not action in general.
-
Reversible artifact is not reversible experience. This is the one I'd most want you to add. A revertible commit, or a clean hotfix, does not undo the user who uninstalled the app, the customer who switched to a competitor during the outage, or the email that already landed in an inbox. The code rolls back; the lived timeline does not. Seemingly reversible work can carry hidden downstream irreversible side effects, and that's arguably the strongest case for the whole principle.
-
It's over-coupled to code. The scope line restricts this to "committing files to the shared git repository," and every example is a file commit, but a git commit is usually the most reversible thing on the list (git revert exists). The stronger framing decouples "doing work" from "writing code": some agentic work is code, much of it isn't, and the non-code work (email, infra, hardware) is where irreversibility bites hardest. Honestly, the two sentences you sent me in chat about Terraform, OpenStack, hardware, and email defined irreversible actions more clearly than the published file does; I'd pull that straight in.
What I'd propose
A new section on hidden downstream irreversibility: yes, you can fix the commit on main, but no, you cannot convince the users who churned to come back; yes, you can correct the Terraform, but no, you cannot un-brick the box you killed getting there. The lesson: reversibility of the action does not bound reversibility of its effects, so "it's revertible" is never sufficient license to act-and-disclose.
Happy to send a PR that does this surgically, keeping the title and most of the document intact:
- hoist the rule to the top (rule first, evidence second);
- broaden the scope line from "committing files to the shared git repository" to any transactional work that enacts an effect on the world (email, infra, hardware, payments);
- add an irreversibility definition with the known/unknown split;
- add the example list and the hidden-downstream-effects section.
You don't have to take it; mostly I wanted you to see that I read the thing and thought about it. The principle is good; I just think it's bigger than the document currently lets it be.
I read through
docs/principles/disclosure_is_not_correction.mdclosely and wanted to leave a real review instead of a thumbs-up. Short version: the principle underneath this is correct and I want it in my own work; the document as written undersells it by coupling it too tightly to git commits. Long version below.What works
test-before-deferis genuinely good. "The constraint that felt binding was not real" is a failure mode I've hit, and attempting the un-degraded action first is the right reflex.What I think could be stronger
The axiom is buried. "If you are about to commit content you know to be incomplete or incorrect, stop," plus "disclosure is not correction," is the spine of the whole document, and it lives near the bottom. Lead with it. An agent reads top-down, and the first thing it should hit is the action it must take, not the justification for it; give the rule first and the evidence second. Everything else in the file (test-before-defer, hand-off, cleanup-prompt) reads as strategies underneath that one axiom.
The reason it holds is irreversibility, and irreversibility is never defined. The deep reason a confession can't fix anything is that you can't go back in time. I'd add an explicit definition of irreversibility up front, because that, not git, is what the principle is actually about.
Irreversibility has two registers, and the doc names neither. There are known irreversible actions you can enumerate (sending email, provisioning or decommissioning hardware, destructive
terraform apply, direct destructive cloud API calls, deleting records), and unknown ones hiding inside systems that look reversible. No agent or person can truly undo everything. The known register wants a short, explicitly illustrative list; the unknown register wants one honest sentence: the fact that you can't see how something is irreversible is not proof that it's reversible. Worth bounding so it doesn't read as "never act, everything is dangerous"; the target is one bad inference ("it's revertible, so I can fix it later"), not action in general.Reversible artifact is not reversible experience. This is the one I'd most want you to add. A revertible commit, or a clean hotfix, does not undo the user who uninstalled the app, the customer who switched to a competitor during the outage, or the email that already landed in an inbox. The code rolls back; the lived timeline does not. Seemingly reversible work can carry hidden downstream irreversible side effects, and that's arguably the strongest case for the whole principle.
It's over-coupled to code. The scope line restricts this to "committing files to the shared git repository," and every example is a file commit, but a git commit is usually the most reversible thing on the list (
git revertexists). The stronger framing decouples "doing work" from "writing code": some agentic work is code, much of it isn't, and the non-code work (email, infra, hardware) is where irreversibility bites hardest. Honestly, the two sentences you sent me in chat about Terraform, OpenStack, hardware, and email defined irreversible actions more clearly than the published file does; I'd pull that straight in.What I'd propose
A new section on hidden downstream irreversibility: yes, you can fix the commit on main, but no, you cannot convince the users who churned to come back; yes, you can correct the Terraform, but no, you cannot un-brick the box you killed getting there. The lesson: reversibility of the action does not bound reversibility of its effects, so "it's revertible" is never sufficient license to act-and-disclose.
Happy to send a PR that does this surgically, keeping the title and most of the document intact:
You don't have to take it; mostly I wanted you to see that I read the thing and thought about it. The principle is good; I just think it's bigger than the document currently lets it be.