Living Artifacts
When producing any markdown artifact, every static snapshot of state must be paired with the command, query, or script that regenerates it. The reader must be able to re-derive the value later without guessing where it came from.
What Counts As A Snapshot
Anything likely to drift between writing and reading time:
- File trees, directory listings, project layouts
- Port numbers, hostnames, URLs, file paths
- Version numbers, deployed commits, image tags
- Row counts, table contents, API response bodies
- Lists of users, repos, tables, services, env vars
- "Currently failing tests" or other status snapshots
- Configuration values that have a canonical home elsewhere
- Counts and aggregates
The Pattern
For each snapshot, include nearby:
- The reproducer first — exact command, query, or script that produces the value.
- The snapshot — clearly framed as a time-of-writing view, not eternal truth.
- A drift caveat — a short note that the value may have changed and can be refreshed with the reproducer.
Single Source Of Truth
When a value already has a canonical home, reference the source instead of duplicating the value in the artifact.
| Bad |
Good |
| Hardcoded port in docs |
Reference the env var or config that defines it |
| Listing names manually in a README |
Point to the directory or generated listing |
| Hardcoded git SHA |
Command that resolves the SHA at read time |
| API field list copied into docs |
Command that introspects the live API |
File References Must Be Clickable
Whenever a markdown artifact mentions a concrete file path, wrap it in a markdown link so readers can jump to it and broken links surface drift quickly.
Apply this to:
- Source files
- Config files
- Sibling docs
- Scripts
- Skill files
- Generated artifacts the reader should inspect
Use relative paths from the markdown file's location. Do not link placeholders, globs, or path-like CLI fragments inside code blocks.
Facts Vs Assumptions
- Facts are verifiable now and should have a reproducer.
- Assumptions are not currently verifiable and must be marked explicitly.
Separate measured facts from interpretations so readers can tell what was observed versus inferred.
Audience Targeting
Setup READMEs are for end users. Contributor docs and AGENTS.md are for maintainers. Put the right level of detail in the right home.
Self-Check
Before publishing, scan every concrete value and ask:
- Will this still be correct in three months?
- If not, is the reproducer next to it?
- If the reader runs the reproducer, will they get the same value?
If not, the artifact is incomplete.
1---2name: living-artifacts3description: Apply when producing any markdown artifact for someone else (or future-you) to read — READMEs, analysis documents, Confluence pages, status reports, troubleshooting write-ups, skill content, conversation summaries, ticket descriptions, post-mortems, snapshots of system state, or any document that contains concrete current-state values. Defines the "snapshot + reproducer" rule (every static value must be paired with the command/query/script that regenerates it), the single-source-of-truth rule (reference canonical homes instead of duplicating values), and fact-vs-assumption marking. Trigger keywords include writing or producing or creating or drafting a README, analysis, Confluence page, status update, summary, snapshot, current state, documenting data, posting findings, file tree, port number, version number, table count, or any concrete value that may drift over time.4---56# Living Artifacts78When producing any markdown artifact, every static snapshot of state must be paired with the command, query, or script that regenerates it. The reader must be able to re-derive the value later without guessing where it came from.910## What Counts As A Snapshot1112Anything likely to drift between writing and reading time:1314- File trees, directory listings, project layouts15- Port numbers, hostnames, URLs, file paths16- Version numbers, deployed commits, image tags17- Row counts, table contents, API response bodies18- Lists of users, repos, tables, services, env vars19- "Currently failing tests" or other status snapshots20- Configuration values that have a canonical home elsewhere21- Counts and aggregates2223## The Pattern2425For each snapshot, include nearby:26271. The reproducer first — exact command, query, or script that produces the value.282. The snapshot — clearly framed as a time-of-writing view, not eternal truth.293. A drift caveat — a short note that the value may have changed and can be refreshed with the reproducer.3031## Single Source Of Truth3233When a value already has a canonical home, reference the source instead of duplicating the value in the artifact.3435| Bad | Good |36| --- | --- |37| Hardcoded port in docs | Reference the env var or config that defines it |38| Listing names manually in a README | Point to the directory or generated listing |39| Hardcoded git SHA | Command that resolves the SHA at read time |40| API field list copied into docs | Command that introspects the live API |4142## File References Must Be Clickable4344Whenever a markdown artifact mentions a concrete file path, wrap it in a markdown link so readers can jump to it and broken links surface drift quickly.4546Apply this to:4748- Source files49- Config files50- Sibling docs51- Scripts52- Skill files53- Generated artifacts the reader should inspect5455Use relative paths from the markdown file's location. Do not link placeholders, globs, or path-like CLI fragments inside code blocks.5657## Facts Vs Assumptions5859- Facts are verifiable now and should have a reproducer.60- Assumptions are not currently verifiable and must be marked explicitly.6162Separate measured facts from interpretations so readers can tell what was observed versus inferred.6364## Audience Targeting6566Setup READMEs are for end users. Contributor docs and `AGENTS.md` are for maintainers. Put the right level of detail in the right home.6768## Self-Check6970Before publishing, scan every concrete value and ask:71721. Will this still be correct in three months?732. If not, is the reproducer next to it?743. If the reader runs the reproducer, will they get the same value?7576If not, the artifact is incomplete.
ArthurZakirov