# Catch documentation drift after a code change

A source change can leave documentation looking perfectly healthy. The page still builds. Its links still work. The instructions may even describe the previous behavior accurately.

The missing signal is that someone needs to look again.

Dewey's source maps declare the files they describe. An explicit review records the current document and covered source. When either changes, `dewey check` asks for another review. It identifies a maintenance task; it does not decide whether a changed line makes the prose false. [How Dewey checks documentation](https://deweydocs.com/docs/overview)

Here is a complete small example using `@deweydocs/dewey` 0.5.1.

## Make the behavior easy to inspect

Create a directory with this `package.json`:

```json
{
  "name": "retry-demo",
  "private": true,
  "type": "module",
  "scripts": { "demo": "bun src/index.ts" }
}
```

Create `src/retry.ts`:

```ts
export const maxAttempts = 3
```

Create `src/index.ts`:

```ts
import { maxAttempts } from './retry.ts'
console.log(`Maximum attempts: ${maxAttempts}`)
```

Run `bun run demo`. It prints `Maximum attempts: 3`. This is a local example that prints a value; it does not make network requests or implement retries.

Install and initialize Dewey:

```sh
bun add -d @deweydocs/dewey@0.5.1
bunx dewey init \
  --purpose "Print the retry budget" \
  --rule "Keep the retry budget in src/retry.ts"
```

The initial `bunx dewey check --json` exits with status 1. It reports draft documents and a map that has never been reviewed. Creating files has not completed the documentation work.

## Establish the reviewed baseline

Replace `docs/src.agent.md` with a map grounded in the two source files:

```md
---
kind: map
title: Retry implementation
covers: [src/*]
---

# Retry implementation

## Files

- `src/index.ts` imports and prints the retry budget.
- `src/retry.ts` exports `maxAttempts`, currently 3.

## Data flow

The entry point reads the exported constant and prints it to stdout.

## Invariants and traps

The budget is defined in one source file. Printing the budget does not perform a network request.
```

Finish the generated `docs/quickstart.md` as well. Keep `kind: guide`, remove `draft: true`, and explain that a reader with Bun can run `bun run demo` from the project root and expect `Maximum attempts: 3`.

After checking those statements against the source, run:

```sh
bunx dewey review docs/src.agent.md
bunx dewey build
bunx dewey check --json
```

The completed example returns:

```json
{ "passed": true, "issues": [] }
```

The review command stores the reviewed state in `.dewey/reviews.json`. Commit that file with the documentation and `.dewey/project.json` so later checks use the same baseline. [Review workflow](https://deweydocs.com/docs/quickstart)

## Change the code, then rebuild

Change the constant in `src/retry.ts` from `3` to `5`. Run the demo again. It now prints `Maximum attempts: 5`, while both documents still describe three attempts.

Run:

```sh
bunx dewey build
bunx dewey check --json
```

Build succeeds. Check exits 1 and reports:

```json
{
  "code": "REVIEW_REQUIRED",
  "path": "docs/src.agent.md",
  "message": "Covered files moved since the last review (changed: src/retry.ts)",
  "fix": "Re-read the covered code, correct the doc, then run dewey review docs/src.agent.md."
}
```

`dewey build` can succeed while `dewey check` exits 1. The build does not record a review.

## Correct the explanation before acknowledging it

Read the change. Update the map's stated value and the quickstart's expected output from three to five. Then record the review and rebuild:

```sh
bunx dewey review docs/src.agent.md
bunx dewey build
bunx dewey check --json
```

The example passes again.

The quickstart needed an edit because it named the old value. The check identified the covered map; it did not automatically discover every sentence affected by the change. Follow the behavior through related guides and references during review. If a guide needs its own source-based review signal, it can declare `covers` and receive an explicit review too.

## Put the signal in CI

Once the repository has a reviewed baseline, run these commands in CI:

```sh
bunx dewey build
bunx dewey check --json > dewey-check.json
```

Check exits 1 when it finds an issue, while the report remains available for inspection. Keep `dewey review` out of the automatic build step. Running it without reviewing the document would erase the signal you wanted.

Dewey also checks references and generated output. It does not run the commands in your documentation. Run `bun run demo` and compare the printed line with the guide. The [CLI reference](https://deweydocs.com/docs/cli) documents the check and review commands used above.