Understandability by humans is a critical aspect of development
State: open/published
Summary
Section titled “Summary”- As agents write more of the code, a human’s ability to understand what changed and why is the constraint that keeps the system steerable.
- Every artifact of development is judged by whether a person can understand it without reading the implementation.
- S-0012-human-reviewable-ui-changes applies it to UI changes.
Statement
Section titled “Statement”Understandability by humans is a critical aspect of development. As agents write more of the code, every artifact of development (a PR, a plan, a screen, a data format, a log) is judged by whether a person can understand it without reading the implementation.
An agent can write code faster than a human can review it line by line. If review depends on reading every line, review becomes the bottleneck or gets skipped. Neither is acceptable. The fix is not to slow the agent down. The fix is to make the agent’s output legible above the level of the diff: a screenshot instead of a markup change, a plain-language summary instead of a stack trace, a plan a person can react to before code exists.
Understanding has to be built into what gets produced. It cannot be left to a reviewer reverse-engineering intent from a diff.
How it applies
Section titled “How it applies”- A UI change ships screenshots, not only a diff of the markup. See S-0012-human-reviewable-ui-changes.
- A PR body states the present shape in plain language: what changed, what it looks like or does now, and what it deliberately does not cover.
- A plan is written so a person can react to it before code exists, not reconstructed from the code after the fact.
- Data is kept in formats a person can open directly, not a binary or a database dump. See P-0007-long-lived-data-formats.
- A system’s shape is surfaced in a document, not left for a reader to infer from source. See P-0009-surface-system-shape.
Implications
Section titled “Implications”- A standard can require evidence a human can review without reading code. S-0012-human-reviewable-ui-changes is one.
- A PR whose only evidence is passing tests is incomplete. Tests show the code works. They do not show a person what changed.
- A design decided inside code, with no plan or screenshot reviewed first, has skipped the step this principle requires.
- An index or dashboard nobody can navigate fails this principle even when the underlying data is correct.
- This principle does not say slow down or write more prose. It says the evidence produced alongside a change must be legible on its own.