Evidence from the codebase supports it. Personal taste does not.
Do not transfer context.
Rebuild the decision.
PDD removes memory from engineering correctness. Each contributor rebuilds the same judgment from current repository evidence.
Definition / 01
“No agent must remember what the repository can prove.”
Memory is private and incomplete. It changes during every summary and handoff.
PDD stores current rules and their active dependencies. A new agent can rebuild the decision without earlier context.
The system
The rule works through four repository links.
Authoritative rulePDD-02@v1Rule · benefit · failure · changes · exceptions · history
01Agent index
Routes each decision to the full rule.
02Pinned citations
Mark code and reviews that depend on it.
03Change protocol
Requires the rule to change before the code.
04PDD CLI
Finds every dependency after a version change.
Its place in the stack
Not documentation. Not another memory.
ArtifactQuestionLifetimeEnforcement
Agent memoryWhat context did I receive?One session or handoffNone
Task planWhat do we do next?One changeCompletion
TestWhat must the code do?Until behavior changesTest runner
Architecture recordWhy did we choose this?HistoricalReview
PDD systemHow must any contributor choose?Until meaning changesTokens and CLI
The lifecycle
Rules evolve without quiet drift.
- 01
Find the judgment
A repeated problem or costly trade can reveal durable judgment. Gather evidence before you write a principle.
- 02
Adopt deliberately
Compare the proposal with every current principle. If one states the judgment, use it. If its meaning changes, advance it. If the decision is independent, add a token.
- 03
Rely explicitly
Pin code comments and review decisions to the current version. Do not copy the full rule.
- 04
Amend at the source
Change the principle before dependent code. If its meaning changes, increment the version.
- 05
Re-prove every site
Let the CLI expose old pins. Review each dependency before its citation receives the new version.
The principle test
A good principle has consequences.
It rules out at least one plausible implementation.
It applies across features and survives one task.
Its implications and exceptions make its limits clear.
A visible process can amend or retire it.
Ready to remove the handoff?