Traceability Signal and CI Gates

Documentation integrity is enforced by three CI quality gates. This page explains each gate, how it fails, and what you must do when your change triggers it.

The FR→page traceability matrix

The FR→page traceability matrix is the canonical mapping between every Functional Requirement (FR) in the PRD and the documentation page that covers it. It is owned by FR415.

Every user-facing FR in the PRD must map to at least one documentation page. If a developer implements a new feature (a new FR or a new registered screen) and no documentation page is created or updated to cover it, the traceability gate (FR415) fails the CI build.

Structure of the matrix

The matrix is maintained as a registry file (the exact path is defined by the FR415 implementation in the traceability/CI epic). Each row records:

The screen registry

The screen registry is a complementary artifact that maps every registered UI screen (by its Pencil node ID and route) to its documentation page. Screens without a documentation page fail the traceability gate.

FR415 — Traceability gate

What it checks: Every FR marked as user-facing in the PRD, and every screen in the screen registry, has at least one non-stub documentation page.

How it fails: The CI build fails with a list of undocumented FRs or screens.

Trigger: The gate runs on every pull request that touches apps/web, apps/agency, apps/tracking, apps/driver, packages/api, packages/database, or apps/docs.

Checking locally before pushing

# Run the traceability gate check
pnpm registry:check

The registry:check Turbo task (defined in turbo.json) runs the traceability validator. If any FR or screen is undocumented, the command exits non-zero and lists the missing pages.

Fixing a traceability failure

1. Identify the failing FR or screen from the command output.
2. Locate the corresponding documentation section in apps/docs/content/docs/.
3. Create or update the MDX page with substantive content (a stub with "Coming soon" does not satisfy the gate).
4. Create the page in all three locales (EN, FR, ES) — the locale-parity gate (FR417) will fail otherwise.
5. Re-run pnpm registry:check to confirm the gate passes.

Documentation update workflow

When you make a subsystem change:

1. Identify affected FRs. Look up the changed feature in the PRD and note its FR identifiers.
2. Look up the matrix. Find all documentation pages that cover those FRs.
3. Update the pages. Reflect the change accurately. Remove any outdated information.
4. Add new pages. If the change introduces a new user-visible feature not covered by any existing page, create a new page.
5. Run the gate. pnpm registry:check must pass.

FR417 — Locale-parity gate

What it checks: Every documentation page that exists in EN also exists in FR and ES.

How it fails: The CI build fails with a list of pages that are present in EN but missing in FR or ES.

The EN locale is the authoring source. Write new pages in page.en.mdx first. The locale-parity gate treats EN as the reference — if EN exists, FR and ES must exist.

FR and ES pages do not need to be machine-translated in real time. For a fast initial ship, you may create FR and ES stubs that mirror the EN content. But the files must exist — missing files fail the gate.

Checking locally before pushing

The locale-parity gate runs as part of pnpm --filter docs build. A build that exits 0 means locale parity is satisfied.

pnpm --filter docs build

If the build reports missing locale pages, create them before pushing.

Adding a new page

Always create all three locale files at the same time:

# Example: new page under maintenance/
apps/docs/content/docs/developer/maintenance/my-page.en.mdx  # author here first
apps/docs/content/docs/developer/maintenance/my-page.fr.mdx  # translate or stub
apps/docs/content/docs/developer/maintenance/my-page.es.mdx  # translate or stub

FR414 — Screenshot-drift gate

What it checks: The screenshots embedded in the documentation match the current UI of the running apps.

How it fails: Playwright compares the current app UI to a committed baseline screenshot. If the visual diff exceeds the tolerance threshold, the gate fails.

Trigger: The gate runs when any app screen changes — a layout update, a new component, a copy change visible in the UI.

When to regenerate screenshots

Regenerate the baseline screenshots when you intentionally change the visual appearance of a documented screen. Do not regenerate screenshots to hide an accidental regression.

Procedure

1. Make your UI change and verify it looks correct in the browser.
2. Run the Playwright screenshot capture script:

pnpm --filter docs exec playwright test --project=screenshots

3. Review the generated screenshots in the output directory.
4. Commit the new baseline screenshots:

rtk git add apps/docs/screenshots/
rtk git commit -m "docs: regenerate screenshots after [screen name] change"

5. Push and confirm the CI gate passes on the pull request.

Screenshot naming convention

Screenshots are named by screen ID (matching the screen registry and Pencil node IDs). Do not rename screenshot files without updating both the screen registry and the documentation page that references them.

Summary: what to run before pushing any change

See also: Maintenance overview · API maintenance · Architecture packages