Keep a Value

A standard for a VALUE.md file at the root of any project - the one-page contract that names who the work is for, what changes for them, and how you'd know the change happened.

Web: keepavalue.com · Author: @dahan_natan

Why

When a builder ships work that doesn't land, the reflex is to build again, faster. The reflex misses the same way. Keep a Value puts a circuit breaker in front of the reflex: three questions you answer before you build, and a six-part gate that asks every next move what value does this earn? before it ships.

The full argument lives in standard/Standard.md. The walk from "I'm not sure if I'm in the build trap" to "I have a conforming VALUE.md" lives in standard/Runbook.md.

A file at the project root, a stable format, a small set of rules. A changelog records what shipped; a VALUE.md records what was supposed to change for the recipient when it did.

Start here

You're a builder. You want one of these things:

The three questions

Q0 - The grounding question (before the three). What is the most recent specific moment you observed your recipient doing the thing your project is meant to change? Not what they said they wanted. Not the persona you imagined. A specific moment, with a date and a place, that you actually watched. If you cannot answer Q0, the three questions below will produce a fiction you can polish to passing every gate. Go observe first.

1. Q1 - Who it's for? One specific person whose life this changes - not "users," not "the team."
2. Q2 - What changes for them? Their behavior or state, observable. Not what you ship.
3. Q3 - How will you know? What proof would tell you the change landed, and how a stranger could check it without you?

The runbook walks you from rough thoughts to three sentences a stranger could verify.

The six-part gate (plus the Q0 grounding precondition)

Before you build, your VALUE.md must pass the Q0 grounding precondition (named in "The three questions" above) AND all six checks below:

1. No hedge-words. No "maybe," "kind of," "ish."
2. A stranger gets it. Hand the three sentences to someone with no context; they can paraphrase them back.
3. You can read it aloud without footnotes. No silent caveats.
4. One recipient across all three sentences. No drift between who in Q1, Q2, Q3.
5. Subject test. Every promise's subject is your behavior, not the recipient's or a third party's. (Promise Theory: you can only promise what you control.)
6. You named what you don't break. For your headline outcome, name one thing that could get worse if you optimize hard for it.

Any one fails - you're not ready to build. All six pass - go build.

Build commands

These targets are for contributors to this repo. If you are adopting the standard, skip to "Repository layout" below.

The standard eats its own cooking. Three CI checks enforce the discipline on this repo itself:

make help                Show all targets
make skeleton            Regenerate Skeleton.md from Template.md
make check               Verify skeleton matches template (drift check)
make check-conformance   Verify shipped contracts have no placeholders or HTML comments
make check-dashes        Verify standard files use ASCII hyphens only (no em-dashes, no en-dashes)
make check-all           Run all three checks - the intended CI check

make check-all must pass before every commit. The check-conformance target is the standard applying its own rule to itself (RFC 2119 pattern: the spec uses its own vocabulary in its own text).

Repository layout

Hard rule (enforced by make check-layout): exactly two top-level directories - standard/ and research/ - plus root-level scaffolding files (README.md, CHANGELOG.md, Makefile, LICENSE, VALUE.md, index.html) and the public-web surface files (llms.txt, robots.txt, sitemap.xml, favicon.ico, apple-touch-icon.png). Nothing else at the root. No exceptions.

This rule has been violated before (in commit 4bcb7fd an audits/ and a translations/ directory landed at the root). The violation was caught, the directories were moved, and the check was added to keep it from happening again. If the layout needs a new top-level concept, the rule changes by explicit ADR - not by drift.

keep-a-value/
├── standard/                 The product. Everything an adopter needs.
│   ├── Standard.md               The standard's own contract. Read first.
│   ├── Template.md               Annotated format - the teacher. Read once.
│   ├── Skeleton.md               Clean placeholder. Copy into your project as VALUE.md.
│   ├── Runbook.md                The how-to: walks you from fog to conforming VALUE.md.
│   ├── lineage.md                Bibliography of borrowed disciplines.
│   ├── stranger-test-prompt.md   The cold-read prompt you can run against any LLM.
│   ├── index.html                The standard, readable in a browser.
│   ├── examples/                 Complete worked VALUE.md files (3 domains).
│   ├── templates/                Adopter-facing templates (acceptance-row, etc.).
│   └── translations/             Translations of the doctrine, one per language code.
├── research/                 All R&D - input to the standard, not part of the product.
│   ├── prior-art/                Literature mining behind each rule.
│   ├── audits/                   Field audits + the q3-acceptance ledger exemplar.
│   ├── references/               Reference summaries of adjacent work.
│   └── experiments/              Empirical tests: round 1/2 + the paired-runs pilot.
├── README.md                 Cold-start orientation (this file).
├── CHANGELOG.md              Versioned change history with evidence trail.
├── Makefile                  Build commands and gates.
├── LICENSE                   Triple license: doctrine CC BY-ND, working surface CC BY, code MIT.
└── index.html                Redirects to standard/index.html (the standard, in browser).

The split is deliberate: standard/ is what an adopter needs; research/ is what produced it; root files are repo-maintenance scaffolding.

Filename convention

Three rules cover every file in this repo:

1. Files inside standard/ use Title.md (Standard.md, Template.md, Skeleton.md, Runbook.md). These are the product.
2. Repo-level docs at the root use UPPER for tool compatibility: README.md (GitHub auto-renders), CHANGELOG.md (standard convention for change history).
3. Everything inside research/ uses lowercase-kebab-case.md. Files in research/prior-art/ are number-prefixed for read-order (01-, 02-, etc.).

Adopter files keep the name VALUE.md no matter where they live - that's the central naming convention of the standard. Every project's contract is VALUE.md. The standard's own contract is standard/Standard.md because it's the standard about VALUE.md files, not a VALUE.md itself.

Lineage

Keep a Value is a distillation, not an invention. It integrates verified primary sources older than itself - Promise Theory, Donabedian's triad, the pre-mortem, the self-explanation effect, and others. Each borrow is named, dated, and cited in standard/Standard.md under "Where this comes from."

The standard's claim is the integration of these disciplines into a one-page-contract format. The individual disciplines are not invented here.

Versioning

main is always the latest. When the standard is ready for tagged releases, version markers will be applied to the source repository. Adopters who need a specific version will reference the corresponding marker. There are no version directories on disk (no v1/, v2/); the version is whatever the current branch carries. Translations, when they exist, will live under translations/<lang>/ parallel to root, with English at the root as the canonical source.

Contributing

Authorship is currently solo (Natan). When the repository opens to outside contributions, a CONTRIBUTING.md will name the process; until then, contribution happens as commits on main with a corresponding CHANGELOG.md entry. The release pattern is already documented in the CHANGELOG: every change names what was added / changed / removed, what was learned, and what was decided.

Status

Proposed for v1.0 with field evidence; the headline Q3 falsifier (paired runs) is the v1.0 → v1.1 gate.

The standard has been applied across 12 real projects in the author's workspace: a custom LLM-CLI client, a written submission to an industry publication, a fundraising-event speech, a sales-prospecting directory, a demo-preparation file for a product team, a documentation contract, and others. Two retrospective field studies have been published in research/audits/2026-06-04-stranger-test-10-rounds/case-studies/:

• Case Study 01 (conversation-transcript analysis) found that VALUE.md adoption is associated with a 68% drop in vague-recipient language and a 68% drop in frustration markers on greenfield work where the team commits to the discipline (directional signal from a 3-pair convenience sample, not inferential). The same signals do not visibly drop when the standard is retrofitted onto a deep existing project (541 prior sessions). The hypothesis sharpens: VALUE.md helps greenfield commitment, not retrofitting.
• Case Study 02 (artifact audit) found that 9 of 12 VALUE.md files in the field have zero hedge words (the gate's strictest rule), 11 of 12 name a specific role-shaped recipient (the Q1 discipline holds), and the standard's own version evolution is visible in the produced artifacts (n=12; descriptive, not inferential).

These studies confirm that adopters write to the standard's format (template compliance, hedge-word rates, recipient specificity). They do NOT confirm that VALUE.md builders outperform description-only builders on recipient-accepted outcomes - that is a different claim that requires the paired-run test. Distinguishing format-compliance evidence from outcome-acceptance evidence is the standard's own rule (proxy theater warning in Runbook §2) applied to its own field studies. The paired-run experiment that would test the outcome claim has not yet been run; it is the v1.0 to v1.1 gate.

All twelve case studies are self-application by one builder. Whether the standard produces the same result for a builder who is not its author has not yet been tested. The standard's own proxy-theater rule applies: the 12 cases are not a blind sample of the Q1 population.

The full history, including two rounds of adversarial LLM testing and the structural responses they produced, is kept in the project's change log.

Licensing

Keep a Value is triple-licensed in a single LICENSE file, mapping license to file role:

• The doctrine (Standard.md, Runbook.md, README.md, CHANGELOG.md, lineage.md) is locked under CC BY-ND 4.0. Share with attribution. Do not modify.
• The working surface (Template.md, Skeleton.md) is open under CC BY 4.0. Fork, translate, and adapt to your team's vocabulary - with attribution.
• The code (Makefile and any future tooling or website code) is open under the MIT License.

The split is deliberate. The doctrine defines what Keep a Value IS - changes to it would be changes to the standard. The working surface is what teams fill in - teams adapting it to their own work need to fork, translate, and specialize freely.

In plain words:

• You can copy and share the doctrine with credit.
• You can fork, adapt, translate, and specialize the Template and Skeleton for your team or organization, with credit.
• You can use, modify, and distribute the code under MIT.
• You cannot publish a modified version of the doctrine's prose, or translate the doctrine publicly without permission.
• You cannot call your adapted Template or Skeleton "Keep a Value" - the trademark stays.

"Keep a Value" and "Value Statement Test" are common-law trademarks of Natan Dahan. No CC license grants trademark rights.

For feedback, suggestions, and translation requests, reach out via @dahan_natan on X or Natan Dahan on LinkedIn.