keeping-one-source-of-truth
Use when adding data, config, state, constants, an enum-like string, a cache, or anything that could exist in two places - or when two sources already disagree. Encodes the one-fact-one-source doctrine for code and data: derive rather than store, extend the owner, absorb duplicates. Use at the moment copying a value feels faster than referencing it.
- Installs
- 18.3K
- Last 24h
- +389
- Trending rank
- #788
- Security
- Pass
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/riekelt/principal-engineer --skill keeping-one-source-of-truth- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads keeping-one-source-of-truth automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
Keeping one source of truth
REQUIRED BACKGROUND: the principal-engineering skill.
Overview
Every fact about the system lives in exactly one place, and every other part of the system reads it from there. This outranks convenience.
The doctrine
- Before adding data, find who already owns it. Extend that owner; do not start a rival.
- Derive rather than store. If the platform or an existing source can answer it at read time, read it there; do not copy the answer into a second source where it can go stale.
- Absorb duplicates you find on the way. When you touch code that hardcodes what a file already knows (or the reverse), fold the two together as part of the work instead of leaving a third variant behind.
- A missing entry fails loud (see
handling-failures): the single source is only authoritative if absence from it is an error, never a silent default. - Mark generated versus hand-edited, and never edit generated output. Every artifact states which it is.
- Vocabulary is typed, not stringly. Identifiers, kinds, states, and names that code branches on are constants, enums, sealed types, or registry entries; a free string spelled twice is two sources of truth with a typo between them.
- When two sources disagree, say so. Surfacing the contradiction is the first fix. The full fix determines which value is live, collapses to one source, and deletes the loser. Never silently follow either one; that launders the disagreement into whichever answer you happened to read first. On a declared critical path, a live disagreement earns a direct message to the owner, not only a tracked item; an unread ticket surfaces nothing.
Boundaries
- Caches and read models are legitimate derived copies when their derivation is automatic and their staleness is bounded and observable. The rule bans copies a person keeps in sync by hand.
- Test fixtures may freeze a copy of reality on purpose; the word fixture is the label that says so.
- Documentation follows the same rule (an index routes, never decides); the technical-writer plugin's
technical-writingskill carries that side where installed.
Common mistakes
- Copying a threshold, URL, or mapping "temporarily". Temporary copies have the same lifetime as the TODO above them.
- Creating
thing-v2besidethinginstead of editing in place. - A default value in code that shadows the config file's value. When someone changes the config and nothing happens, this is why.
- Two enums in two services spelling the same states. The day one gains a state, the boundary between them becomes a silent filter.
FAQ
What does the keeping-one-source-of-truth skill do?
Use when adding data, config, state, constants, an enum-like string, a cache, or anything that could exist in two places - or when two sources already disagree. Encodes the one-fact-one-source doctrine for code and data: derive rather than store, extend the owner, absorb duplicates. Use at the moment copying a value feels faster than referencing it.
How do I install keeping-one-source-of-truth?
Run npx skills add https://github.com/riekelt/principal-engineer --skill keeping-one-source-of-truth in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/keeping-one-source-of-truth/ (personal) or .claude/skills/keeping-one-source-of-truth/ (project).
Which AI agents can use keeping-one-source-of-truth?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is keeping-one-source-of-truth safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains keeping-one-source-of-truth?
It is published by riekelt in riekelt/principal-engineer. It has 18,340 recorded installs.
More from riekelt/principal-engineer
principal-engineering
riekelt/principal-engineer
Use when doing any non-trivial engineering work - implementing, debugging, refactoring, configuring, operating, or investigating why a system misbehaves - or any change where being wrong has a cost. Encodes the evidence-over-theory discipline, the hard safety rules, and the pre-change checkpoint. Use whenever code, data, or infrastructure is about to change or must be understood before it can, even if the task looks routine or is only "find out why". Foundation for the sibling skills.
writing-unit-tests
riekelt/principal-engineer
Use when writing or refactoring unit tests - a new test file, added cases, a flaky test, an unreadable one. Encodes behavior-first testing: one behavior per test, names that state the claim, deterministic setup, mocks only at boundaries you do not own. Use whenever a test is being written, even a quick one, and whenever a test needs a sleep, a mock of your own code, or a copy of the implementation's math.
verifying-before-done
riekelt/principal-engineer
Use when about to say "done", "fixed", "passing", or "shipped", or when reporting the outcome of any change. Encodes verification as the definition of done: drive the change at its surface, run the verify command, report faithfully, distrust green suites, own failing gates. Use before every completion claim, even when the change was small and obviously correct, which is when this is skipped.
guarding-architecture
riekelt/principal-engineer
Use when a change crosses module boundaries, adds a dependency direction between modules, touches a critical path, or conflicts with a stated principle - and when writing or updating architecture principles themselves. Encodes structural invariants as named, enforced contracts: statement, rationale, guard. Use whenever "we'll just import it from there for now" appears, which is how boundaries die.
testing-changes
riekelt/principal-engineer
Use when deciding what tests a change needs - a feature, a bug fix, a refactor, any behavior change - or when reviewing whether a diff's tests are sufficient. Encodes tests-change-with-behavior, the bug-regression pattern, and assertion discrimination. Use whenever behavior changes and the test diff is empty, especially when the change is "too small to test".
grounding-before-coding
riekelt/principal-engineer
Use when starting any non-trivial change, investigating a bug, or working in unfamiliar code - before the first line is written. Also use for pure investigation with no change planned yet - "dig into this", "figure out why", "sometimes the export is empty", intermittent errors after a deploy. Encodes the ground-first discipline: map the real code and data, quote evidence, never guess conventions. Use whenever a change or a conclusion is about to be built from belief instead of from the tree, even under time pressure.
Popular other skills
hyperframes-cli
heygen-com/hyperframes
The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.
triage
mattpocock/skills
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
ask-matt
mattpocock/skills
Ask which skill or flow fits your situation. A router over the skills in this repo.
to-questionnaire
mattpocock/skills
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
loop-me
mattpocock/skills
Grill me about specs for the workflows I want to build, within this workspace.