A complete example

One rule gives each new agent a clear decision and makes later changes visible.

This example uses Validate at Use. It connects a permission rule to the code and reviews that depend on it.

The problem

A new agent has no earlier context. Its task is to let a user download an export after a preview.

The user can lose permission between the preview and the download. Agents repeatedly add locks, expiry jobs, and coordination code to close each gap.

The team instead makes the download operation responsible for current permission. One check at that boundary replaces many earlier attempts to preserve permission.

1. Write the rule

The Rule owns the required choice and its binding exceptions. The short Rationale explains the behavior that earned it.

# PDD-02 — Validate at Use
Token: PDD-02
Version: v1

## Rule
When code uses an artifact, validate the important facts.
A check from creation or preview does not stay true.
Name the validation checkpoint and the facts it guarantees.

If a fact cannot change, name that fact before
you omit its use-time check.

## Rationale
Agents add locks and cleanup jobs for each timing gap.
One use-time check replaces those earlier repairs.

## History
- v1 (2026-08-24): Adopted after repeated timing fixes.

2. Index the rule

The agent index gives the rule a short, discoverable entry.

## Principles

- **PDD-02@v1 — Validate at Use** — Check critical facts at use.
  → `docs/principles/pdd-02-validate-at-use.md`

Read the full principle before you change covered code.

PDD-02 identifies the principle. @v1 pins the entry to version one. The linked file supplies the full rule.

3. Cite the dependency

The comment states the local dependency. It gives the next contributor a path to the complete rule.

async function downloadExport(userId, exportId) {
  // PDD-02@v1: This download checks current permission before use.
  // The preview check only gives early feedback.
  await requireDownloadPermission(userId, exportId);
  return readExport(exportId);
}

The preview check gives early feedback. The download operation makes the permission decision from current facts.

4. Review the decision

A reviewer cites the same token to explain why the earlier preview can become stale.

Working as designed under PDD-02@v1.
The download checks current permission before it reads the export.
An old preview does not grant permission.

Tests still cover the behavior. For example, a test removes permission after the preview and expects the download to fail.

5. Change the version

After a meaning change, the team advances the principle to v2. The agent index now cites PDD-02@v2. The old code citation still states PDD-02@v1.

$ pdd check

src/exports/download.js:2 [PDD106]
PDD-02@v1 is stale; review this site against PDD-02@v2

pdd check: FAILED (1 problem)

The CLI makes the old dependency visible. A contributor reads version two and reviews the download before changing its citation.