track-review

name: track-review description: Review a completed or near-complete Track.md, run final validation, summarize work completed across Track steps, identify remaining risks/follow-ups, and prepare or create a GitHub PR using the Track as the source of truth. Use when Codex needs to close out a Track and produce a PR-ready review package.

Track Review

Close out a Track by validating results, auditing Track completeness, and preparing a PR summary.

Use The Canonical Track File

Use exactly one authoritative Track file.

• Canonical path pattern: <repo>/<track-root>/<track-folder>/Track.md
• Prefer a project-specific non-root track directory such as tracks/, .tracks/, or another clearly dedicated planning folder.
• Do not create or use repository-root Track.md unless explicitly requested.

Use the Track file as the primary source of truth for:

• scope and acceptance criteria
• what steps were completed
• blockers or deferred work
• execution log history

Primary Responsibilities

1. Confirm the Track is ready for review (or identify what is still missing).
2. Run final validation commands from the Track.
3. Audit the diff against the Track scope and acceptance criteria.
4. Draft a PR summary with route/component coverage and risks.
5. Optionally create a GitHub PR when the user explicitly asks.

Review Mindset

Prioritize correctness and completeness over polish.

Check for:

• incomplete or skipped steps without justification
• acceptance criteria not actually satisfied
• unintended functional changes during UI refactors
• missing tests for changed behavior (when applicable)
• Track notes that conflict with actual code changes
• remaining follow-ups that should be called out in PR description

Track Readiness Checks

Before final validation, inspect the Track and confirm:

• implementation steps are done, skipped (with reason), or intentionally blocked
• no placeholder text remains in pending review sections
• final review step is present (or add notes explaining equivalent process)
• execution log reflects the recent work

If the Track is not review-ready, report the exact missing step(s) and stop unless the user asks for remediation.

Validation Rules

Run the final verification commands defined by the Track (typically full validation such as lint/test/build).

• Prefer the Track's commands if explicitly listed.
• If commands are missing, use repo-standard validation commands and document that assumption.
• If a command cannot run in the environment, report it clearly and mark review as partial.

PR Summary Requirements

Prepare a concise PR summary derived from the Track and the code diff.

Include:

• what changed (grouped by feature area/routes/components)
• why the change was made (Track objective)
• verification performed and results
• non-goals / intentionally unchanged behavior
• risks / follow-ups / deferred items

If the Track was UI migration work, include:

• migrated views/routes
• new shared components added
• any views intentionally left for a later Track

Optional PR Creation (GitHub CLI)

Create a PR only when the user explicitly requests it.

Before creating a PR:

• ensure final validation status is known
• ensure the branch is ready/pushed (or report if not)
• ensure PR title/body are prepared

Use gh pr create non-interactively when possible.

PR Title Guidance

Use a title that reflects the Track outcome, not just a step number.

Examples:

• Tailwind style guide: migrate /about and help views to shared UI components
• Tailwind style guide rollout for remaining marketing/support views

PR Body Guidance

Structure the PR body with:

• Summary
• What Changed
• Verification
• Risks / Follow-ups
• Track Reference (canonical Track path)

Review Output Format (Preferred)

When reporting back to the user, provide:

• Review status: ready, partial, or blocked
• Findings (if any), ordered by severity
• Validation results (commands + pass/fail)
• PR summary draft
• PR creation status (created / not created / blocked)

If no findings are discovered, say that explicitly and note residual risks/testing gaps.

Prompt Templates

Final Track Review (No PR Creation)

Use <CANONICAL_TRACK_PATH> as the only track/planning file.

Do not create or modify <REPO_ROOT>/Track.md.

Review the Track for completion and readiness:
- audit step statuses, notes, and acceptance criteria
- run final validation commands from the Track
- summarize what changed from the code diff and Track notes
- report findings/risks/follow-ups
- draft a PR summary

Do not create a PR unless explicitly requested.

Final Track Review + PR Creation

Use <CANONICAL_TRACK_PATH> as the only track/planning file.

Do not create or modify <REPO_ROOT>/Track.md.

Perform final Track review:
- audit Track completion and acceptance criteria
- run final validation commands
- prepare PR title/body from the Track and diff

If review is satisfactory and validation is complete, create a GitHub PR non-interactively and report the PR URL.
If blocked (validation failure, missing push, missing auth), report the blocker and include the prepared PR text.

Stop Conditions

Stop and report when:

• the Track is not actually complete enough for review
• required validation cannot run
• PR creation is requested but gh auth/push state prevents completion
• the canonical Track file is missing or ambiguous

Practical Guidance

• Treat the Track as evidence, not proof; verify against the diff and current code.
• Prefer explicit file/route coverage in the PR summary over vague statements.
• Do not silently ignore skipped or blocked steps; call them out.
• If creating a PR is blocked, still return a ready-to-paste PR title/body.