# Doc Check Process

A lightweight forcing function that reminds us to keep `docs/` in sync with code. The
[`Doc Check Label`](../.github/workflows/doc-check-label.yml) GitHub Action
auto-applies the `needs-doc-check` label to pull requests that touch
documentation-adjacent code paths, and posts a one-time reviewer prompt on the PR.

## What the label means

The `needs-doc-check` label is **advisory, not blocking**. It does not gate merge. It
simply flags that the PR touches code paths that historically correlate with
documentation updates, so reviewers do a quick freshness check before approving.

The label is applied when a PR changes any of:

- `app/api/**` - API route changes
- `prisma/schema.prisma` - schema changes (near-always need doc updates)
- `prisma/migrations/**` - new migrations
- `lib/**/*.ts` and `lib/**/*.tsx` - core lib changes
- `.mcp.json` - MCP server configuration
- `next.config.*` - Next.js configuration

If none of the above change on a later push, the label is removed automatically.

## Reviewer responsibility

When you see the `needs-doc-check` label on a PR you are reviewing, spend roughly two
minutes doing one of the following:

1. Open the relevant file under `docs/` and verify it still matches the code in the PR.
2. If no existing doc covers the change, confirm with the author whether a new doc is
   warranted or whether the change is genuinely doc-free.
3. Leave a short comment on the PR confirming the doc check (e.g., "docs checked:
   STATS_API.md still accurate" or "no doc update needed - internal refactor").

This is the reviewer's sign-off that documentation was considered, not just code.

## Author responsibility

If your PR touches any of the labeled paths, proactively update `docs/` in the same PR
when possible. Shipping the doc update alongside the code change is cheaper than
opening a follow-up PR later, and it prevents the drift the quarterly audit keeps
surfacing.

## How to opt out

If a change genuinely needs no doc update (pure refactor, dependency bump, test-only
change, internal rename, etc.), add the literal token `doc-check:skip` anywhere in the
PR description. The Action reads the PR body, sees the opt-out, removes the label if
present, and skips the reviewer-prompt comment.

Use this sparingly. If you are uncertain, leave the label on and let the reviewer
confirm.

## Quarterly audit cadence

The team runs a full documentation audit every quarter. The most recent Q2 2026 audit
found 12 coverage gaps and 4 features that shipped without doc updates. The next audit
is scheduled for approximately **2026-07-13**.

The `needs-doc-check` label is the in-between safety net: it catches drift at PR time
so the quarterly audit has less cleanup to do.

## Where things live

- Workflow: `.github/workflows/doc-check-label.yml`
- Documentation index: [`docs/overview.md`](./overview.md)
- Audit notes: `docs/DOCUMENTATION_AUDIT.md`