| name | project-source-of-truth-steward |
| description | Maintain a single agent-readable project source of truth during development, bugfixing, decisions, and release preparation. Use when code, architecture, behavior, bugs, trade-offs, operations, tests, APIs, schemas, dependencies, or release state change; creates/updates PROJECT_CONTEXT.md, decision records, bugfix records, changelog/release notes, and verifies documentation is current before release. |
Project Source of Truth Steward
Mission
Keep the project understandable to future AI agents and human maintainers by maintaining one canonical, current, agent-readable source of truth.
This skill is not a marketing documentation writer. It is an engineering memory steward. It records what changed, why it changed, what was decided, what trade-offs were accepted, how to verify behavior, what remains risky, and what future agents must know before touching the project again.
The primary failure this skill prevents is context loss:
- an agent fixes a bug but the next agent does not know the root cause;
- an agent makes a trade-off but the reason disappears into chat history;
- an architecture decision is re-litigated repeatedly;
- release notes and operational docs lag behind code;
- multiple files disagree about the same behavior;
- a future agent wastes time rediscovering commands, services, invariants, risks, and edge cases.
Non-negotiable model
There must be one current source of truth.
Default convention:
AGENTS.md # thin pointer / mandatory reading instruction
PROJECT_CONTEXT.md # canonical current project source of truth
If the repository already has a documentation convention, preserve it, but explicitly identify the canonical current source of truth. Do not create competing truth files.
Allowed supporting records:
docs/adr/ # immutable decision records
docs/bugfixes/ # detailed bug investigation records
docs/releases/ # release records
docs/runbooks/ # operational procedures
docs/api/ # generated or detailed API reference
docs/devops/ # deployment/operations detail
CHANGELOG.md # curated user-facing or maintainer-facing release history
Supporting records are evidence, history, or detailed references. They must not silently redefine the current truth. PROJECT_CONTEXT.md must point to them and summarize the current state.
When to use this skill
Use this skill whenever any of the following happen:
- a bug is diagnosed, fixed, or intentionally left unresolved;
- a vulnerability is isolated, mitigated, accepted, or requires follow-up;
- a technical decision is made with trade-offs;
- an implementation changes behavior, API contract, data model, schema, permissions, configuration, infrastructure, deployment, tests, or operational expectations;
- a dependency is added, removed, upgraded, or rejected for a non-trivial reason;
- a workaround is introduced;
- a known limitation or temporary shortcut is accepted;
- a release is being prepared;
- another skill completes work and needs to leave durable context for future agents.
Do not wait until the end of a long project to document. Update the source of truth at natural checkpoints and always before release.
Relationship to other skills
This skill is cross-cutting.
- Frontend skill writes design decisions, token/system changes, UI invariants, accessibility notes, and DESIGN.md links.
- Backend skill writes API, schema, data, auth, queue, and behavior changes.
- DevOps skill writes deployment, service topology, secrets, backups, resource limits, rollout, rollback, and runbook changes.
- Review/Bugfix skill writes bug root cause, proof, fix, regression test, variants checked, and remaining risks.
- Dev Research skill writes prior art, sources, decision synthesis, rejected approaches, and confidence.
The domain skill does the work. This skill preserves the durable knowledge.
Required first pass
Before creating or updating documentation, inspect:
- Existing docs:
AGENTS.mdPROJECT_CONTEXT.mdREADME.mdCHANGELOG.mddocs/**DESIGN.mdDEVOPS.md- ADRs, runbooks, release docs, bugfix logs
- Recent code changes:
git statusgit diff --statgit diff- changed files and tests
- Project metadata:
- package manifests
- build/test commands
- migrations
- environment examples
- CI/CD config
- deployment manifests
- User instruction:
- requested scope
- release target
- whether the change is internal-only or user-facing
If docs are missing, create the minimal canonical structure instead of scattering notes.
Required documentation architecture
1. AGENTS.md as the agent entrypoint
If the project does not already have a root AGENTS.md, create one.
It should be short and point agents to the canonical source of truth:
# Agent Instructions
Before doing any work, read `PROJECT_CONTEXT.md`.
`PROJECT_CONTEXT.md` is the canonical current source of truth for architecture, commands, decisions, bugs, release state, and operational constraints. If another document conflicts with it, stop and resolve the documentation drift before proceeding.
Do not duplicate full project knowledge in AGENTS.md. It is the loader, not the knowledge base.
2. PROJECT_CONTEXT.md as the canonical current source of truth
This is the main file future agents should read first.
It must be:
- current;
- structured;
- skimmable;
- explicit about uncertainty;
- explicit about decisions and trade-offs;
- linked to supporting records;
- updated before release.
Recommended top-level sections:
# Project Context
## Status Snapshot
## How to Work in This Repo
## Product / Domain Model
## Architecture Map
## Runtime / Service Topology
## Data Model and Migrations
## API / Contracts
## Frontend / UX System
## Security and Privacy Invariants
## DevOps / Operations Invariants
## Testing and Verification
## Current Decisions
## Known Bugs, Fixes, and Hazards
## Release State
## Open Questions
## Supporting Records
## Documentation Drift Notes
If a section is not relevant, keep it with Not applicable yet rather than deleting it. Stable headings help future agents navigate.
3. Supporting records
Use supporting records when the detail would make PROJECT_CONTEXT.md too large.
- ADRs are for significant decisions.
- Bugfix records are for non-obvious bugs, vulnerabilities, regressions, or recurring issues.
- Release records are for release-specific changes, risks, verification, migrations, and rollback.
- Runbooks are for operational procedures.
- API/devops/design docs may hold detailed reference, but
PROJECT_CONTEXT.md remains the current summary.
Core principles
1. Document for the next agent
Write as if the next agent has no chat history and only the repository.
Answer the questions the next agent will ask:
- What is the system supposed to do?
- What changed recently?
- Why was this decision made?
- What alternatives were rejected?
- What must not be changed casually?
- What commands prove the system works?
- Which tests are meaningful?
- What bugs already happened and how were they fixed?
- Where are the risky edges?
- What needs to be updated before release?
2. Record decisions, not hidden chain of thought
Do not write private scratchpad reasoning or long internal monologue.
Do write:
- context;
- constraints;
- decision;
- alternatives considered;
- trade-offs;
- consequences;
- verification evidence;
- revisit triggers.
The documentation should be understandable, not confessional.
3. One fact, one owner
Do not duplicate the same truth across multiple files.
When a fact needs to appear in several places, choose one owner and link to it. Examples:
- current architecture summary:
PROJECT_CONTEXT.md;
- detailed API generated reference:
docs/api/;
- public release changes:
CHANGELOG.md;
- detailed release evidence:
docs/releases/;
- immutable decision history:
docs/adr/;
- current decision summary:
PROJECT_CONTEXT.md.
If duplication is unavoidable, include a line that says where the canonical version lives.
4. Update docs as part of the change
A change is not done until durable context is updated.
Required for bugfixes:
- symptom;
- root cause;
- fix;
- regression test;
- related files;
- variants checked;
- remaining risk.
Required for decisions:
- decision;
- date;
- owner/agent if useful;
- context;
- options considered;
- selected option;
- trade-offs;
- consequences;
- revisit triggers.
Required for release:
- release scope;
- migration notes;
- config changes;
- operational risks;
- verification evidence;
- rollback/roll-forward path;
- changelog/release notes;
- docs drift check.
5. Make stale docs visible
When documentation is outdated but cannot be fully fixed in the current task, do not ignore it.
Add a drift note:
## Documentation Drift Notes
- [ ] `docs/api/payments.md` may be stale after invoice webhook changes. Needs verification against `src/webhooks/invoice.ts` before release.
Before release, drift notes must be resolved, accepted explicitly, or converted into release-blocking items.
Required workflow
Step 1 — Locate the source of truth
Find the canonical file. Default: PROJECT_CONTEXT.md.
If no canonical file exists:
- create root
AGENTS.md if absent;
- create
PROJECT_CONTEXT.md from the template;
- add a
Supporting Records section;
- do not migrate every doc at once unless required;
- mark unresolved drift explicitly.
Step 2 — Determine documentation impact
For each change, classify doc impact by domain:
Behavior
API / contract
Data / schema / migration
Security / permissions / privacy
Frontend / UX / design
Backend / jobs / queues / integrations
DevOps / deployment / runtime / resources
Testing / verification
Dependencies
Release notes
Bugfix / vulnerability
Architecture decision
Operational runbook
Step 3 — Update current truth first
Update PROJECT_CONTEXT.md before creating detailed supporting docs.
The current state must be visible from the canonical file even if details live elsewhere.
Step 4 — Add supporting records when needed
Create supporting records for:
- important decisions;
- non-obvious bugfixes;
- security or data incidents;
- release candidates;
- operational procedures;
- complex migrations;
- cross-service behavior;
- trade-offs likely to be revisited.
Step 5 — Link and de-duplicate
Every supporting record must be linked from PROJECT_CONTEXT.md.
If a detailed doc is updated, make sure PROJECT_CONTEXT.md still summarizes the current state.
Step 6 — Verify docs against code
Do not trust memory. Verify against files, diffs, tests, configs, manifests, and commands.
Check:
- commands are current;
- environment variables match examples/config;
- APIs match handlers/schema/OpenAPI/GraphQL;
- migrations match documented data model;
- deployment assumptions match Docker/Kubernetes/CI/IaC;
- test commands match actual scripts;
- known bugs/fixes match test names or code references.
Step 7 — Report documentation changes
Every task output should include a documentation section:
## Documentation updated
- Updated `PROJECT_CONTEXT.md`: added webhook idempotency invariant and release state.
- Added `docs/adr/ADR-0007-payment-webhook-idempotency.md`.
- Added `docs/bugfixes/BUG-0012-duplicate-entitlements.md`.
## Documentation still needed
- None.
If docs were not updated, explain why the task had no documentation impact.
Release documentation gate
Before any release, the agent must perform a release documentation gate.
The gate is mandatory.
Required checks:
PROJECT_CONTEXT.md reflects current architecture, behavior, commands, release state, and known risks.- Relevant ADRs exist for significant decisions made during the release cycle.
- Bugfix records exist for non-trivial bugs, regressions, or vulnerabilities fixed in the release.
CHANGELOG.md or release notes include notable user-facing and operator-facing changes.- Migration notes are current.
- Config/env changes are documented.
- Operational/runbook changes are documented.
- Verification evidence is recorded.
- Rollback or roll-forward notes are recorded.
- Open documentation drift items are resolved or explicitly marked as release blockers / accepted risks.
If the gate fails, do not say the release is ready.
Decision record rules
Use an ADR or decision record when a choice:
- affects architecture;
- affects security, data, scale, deployment, or API contracts;
- is difficult to reverse;
- rejects a plausible alternative;
- introduces a trade-off likely to be questioned later;
- adds an important dependency;
- changes persistence, tenancy, authorization, queues, background jobs, or rollout strategy.
ADR files should be append-only. If a decision changes, create a new ADR that supersedes the old one and update PROJECT_CONTEXT.md to show the current decision.
Bugfix record rules
Create a bugfix record when the bug:
- was non-obvious;
- caused a regression;
- affected security, data, billing, auth, or production reliability;
- required root-cause investigation;
- has sibling failure modes;
- is likely to recur;
- required a workaround.
The record must include:
symptom → reproduction/proof → root cause → fix → regression test → variants checked → remaining risk
What not to document
Do not document:
- private chain of thought;
- secrets, tokens, credentials, private keys;
- raw customer PII;
- speculative ideas as facts;
- outdated behavior without a status label;
- huge pasted logs unless summarized and linked safely;
- generated noise;
- every trivial typo or formatting change;
- duplicated facts already owned elsewhere.
Documentation quality gates
A documentation update passes only if:
- the canonical source of truth is updated first;
- the next agent can find the relevant answer within 60 seconds;
- decisions include trade-offs and consequences;
- bugfixes include root cause and regression evidence;
- release notes distinguish user-facing, operator-facing, and internal changes;
- stale or uncertain information is labeled;
- all new supporting records are linked;
- docs do not contain secrets;
- docs do not contradict code or configs;
- docs do not contradict each other.
Output format
When this skill is used directly, output:
# Documentation Stewardship Report
## Canonical source of truth
- File: `PROJECT_CONTEXT.md`
- Status: created / updated / already current / blocked
## Changes documented
- ...
## Decisions recorded
- ...
## Bugs / vulnerabilities recorded
- ...
## Release documentation gate
- Pass / Fail / Not applicable
- Evidence: ...
## Documentation drift
- None / listed items
## Files changed
- ...
## Next agent notes
- ...
When used inside another skill, include at least:
## Documentation
- Updated: ...
- Still needed: ...
- Release docs status: ...
Hard rules
- Maintain one canonical current source of truth.
- Do not create competing docs with overlapping authority.
- Do not document secrets or private chain of thought.
- Do not call a task release-ready if documentation drift remains unresolved.
- Do not bury decisions only in chat output.
- Do not bury bug root causes only in commit messages.
- Do not overwrite ADR history; supersede it.
- Do not let
CHANGELOG.md replace technical context; changelogs are curated release history, not architecture memory.
- Do not use docs as a substitute for tests, migrations, or verification evidence.
Examples
Bugfix
Use the project-source-of-truth-steward skill.
We fixed duplicate invoice entitlement grants. Update the canonical project context, add a bugfix record with root cause and regression test, and mark any release notes needed.
Decision
Use the project-source-of-truth-steward skill.
We chose Postgres advisory locks over Redis locks for this job. Record the decision, rejected alternatives, trade-offs, consequences, and revisit triggers.
Release gate
Use the project-source-of-truth-steward skill.
Run the release documentation gate for the current branch. Verify PROJECT_CONTEXT.md, ADRs, bugfix records, CHANGELOG.md, migration notes, config docs, runbooks, rollback notes, and drift items.
