REVIEW

Review Guide

Use this file when reviewing changes in the Trackdub engineering wiki (Trackdub.wiki).

This is a reviewer checklist for documentation PRs (or direct wiki edits), not an authoring style guide. Source of truth for shipped behavior remains the active code repos: trackdubllc/Trackdub (public core) and trackdubllc/Trackdub-gated (desktop). Prefer linking to ADRs and ops docs in those repos when they exist.

Automated review (Bugbot)

If Cursor Bugbot (or similar) is configured for this repository, it should follow this checklist. Human reviewers still own the final merge bar.

Bugbot should surface the same blocking issues as Automatic review stops below (fake readiness, stale architecture claims, inventing APIs that do not exist).

Review priorities

Review in this order:

1. Factual accuracy vs current code
2. Scope control (docs only)
3. Architecture and readiness honesty
4. Navigation / wiki structure
5. Link and naming consistency
6. Clarity for agents and humans

Approval standard

Do not approve a change if any of these are unclear:

• What pages changed
• Whether claims match shipped behavior in core/gated/api/portal
• Whether readiness states are described honestly
• Whether links (wiki [[Page]] and external URLs) still resolve
• Whether the change invents architecture that is not implemented

Checklist

1. Scope

• The change is documentation only (markdown / wiki navigation).
• Unrelated page rewrites are absent or clearly separated.
• Product code changes are not smuggled into this wiki repo.

2. Accuracy and honesty

Treat these as request-changes items, not suggestions.

• Provider registered, model downloaded, stage ran, stage skipped, and stage succeeded remain distinct. Docs never collapse them into "ready."
• Domain-depends-on-nothing and other layer rules match Layered-Dependency-Rules and current core/gated ownership.
• Desktop vs public-core vs API vs portal ownership is stated correctly after the source split.
• Commands, TFMs, and paths match current AGENTS.md in the owning repo.
• Unknown or aspirational features are labeled as backlog / planned, not shipped.

3. Structure and navigation

• New pages are linked from Home or the relevant section map.
• _Sidebar.md / _Footer.md updated when navigation changed.
• Page titles and [[Wiki-Links]] stay consistent with filenames.
• Duplicate pages for the same topic are avoided or clearly superseded.

4. Cross-repo pointers

• Prefer citing canonical docs in active repos (ADRs, ops, specs) over copying large frozen monorepo text when the live doc exists.
• Archive / historical notes are labeled as archive when they describe pre-split monorepo layout.

5. Writing quality

• Concrete and falsifiable. Prefer exact paths, commands, and states.
• Avoid em dashes in user-facing prose.
• No secrets, tokens, or private machine paths.

Automatic review stops

Request changes immediately if a change does any of the following:

• Describes fake readiness (registered as ready, skipped as succeeded, etc.).
• Documents an API, stage, or architecture boundary that does not exist in the owning repo without labeling it planned.
• Conflates Trackdub (core), Trackdub-gated, api.trackdub, and portal ownership.
• Breaks sidebar / Home navigation without updating links.
• Commits secrets or private credentials.

Review comment style

Prefer comments that are concrete and falsifiable:

• Point to the exact page and claim.
• State the mismatch with current code or ownership.
• Suggest the narrowest correction (soften claim, add "planned", or link the canonical ADR).

Good review comments usually sound like:

• "This collapses 'model downloaded' into 'ready'. Split the states."
• "Desktop trust-ring content belongs under gated ownership, not public core."
• "Command uses the old monorepo Trackdub.sln path. Update to current repo entrypoints."
• "New page is orphaned from Home and _Sidebar.md."

Minimum merge bar

A wiki change is ready when:

• Claims match current shipped behavior or are clearly marked planned.
• Navigation still works.
• Ownership across split repos is accurate.
• Readiness language stays honest.