review-fix-gaps

name	review-fix-gaps
description	Review a plan, issue, spec, PR, current diff, or implementation against an authoritative source of truth; identify missing, incorrect, risky, overcomplicated, or unverifiable work; patch clear gaps when requested; optionally run an advisory external reviewer (e.g. the codex-pr review loop / codex/AGY) for implementation diffs.

Review Fix Gaps

Review a plan or built work against the authoritative spec, then improve the artifact in the same pass.

Quick Start

Use this skill when the task is both:

• Compare an artifact to a source of truth
• Improve the artifact, not just review it

Supported artifacts:

• Plan or issue before implementation
• PRD, acceptance criteria, or design note
• In-progress or completed implementation

If the user only wants findings, stay in review mode and do not edit. If the user wants greenfield implementation from a clear ticket, use a build-oriented skill instead.

Source of Truth

Establish the canonical spec before judging the implementation.

Prefer sources in this order:

1. Explicit instructions in the current request
2. Linked or attached spec artifacts: PRD, design, acceptance criteria, decision doc
3. Ticket or issue body and its latest clarifying comments
4. Existing code patterns only as implementation guidance, not as the product spec

If sources conflict, prefer the most recent explicit decision and call out the conflict. If no authoritative source exists, ask for one or switch to review-only mode instead of inventing requirements.

Workflow

1. Load the Spec

• Read the source artifact in full before judging the code
• Extract concrete requirements, acceptance criteria, constraints, and anti-goals
• Turn them into a short checklist you can map to code

2. Choose the Mode

Pick the branch that matches the artifact under review.

Plan / Spec Mode

Use when there is no implementation yet, or when the user wants the plan, issue, or spec improved before coding starts.

Review for:

• missing requirements or hidden assumptions
• ambiguous acceptance criteria
• sequencing or dependency mistakes
• unnecessary complexity or over-design
• unclear ownership, rollout, or verification
• decisions that should be explicit before implementation

Improve the artifact directly when requested:

• rewrite the plan
• tighten acceptance criteria
• add comments or feedback
• edit the issue or spec text

Implementation Mode

Use when code, prompts, schema, UI, or tests already exist and need review against the spec.

3. Inspect the Current State

• Read the actual implementation, diffs, and nearby integration points
• Inspect tests, schema changes, prompts, UI wiring, and persistence paths when relevant
• Build a status map: done, partial, missing, incorrect, unnecessary

If you are in Plan / Spec Mode, inspect the current artifact instead of code and build the same status map against the source of truth.

4. Review with a Strong Rubric

Check for more than missing features:

• Spec gaps: required behavior not implemented or only partially implemented
• Plan gaps: required decisions or execution details not captured clearly enough to build safely
• Correctness risks: bugs, wrong data flow, broken write path, stale reads, invalid assumptions
• Simplification opportunities: duplicated logic, unnecessary abstractions, fallback stacking, avoidable complexity
• Consistency gaps: implementation drifts from local patterns, naming, or architecture
• Verification gaps: missing or weak tests for the changed behavior
• UX or product gaps: confusing defaults, missing states, misleading controls, weak observability
• Ownership gaps: work presented as done without an honest done-claim — unverified by running it, merged but not confirmed live where it runs, no follow-up or observation registered (see the owner-review skill)

Prefer root-cause fixes over defensive layering. If the wrong value can be written, resolved, or materialized upstream, fix that path first.

5. Improve the Artifact

In Plan / Spec Mode:

• patch the issue, plan, or spec directly when requested
• add precise comments where decisions, risks, or missing scope should be called out
• simplify the plan if phases or abstractions are unnecessary
• leave explicit open questions for product or engineering decisions you cannot safely invent

In Implementation Mode:

• Patch the highest-confidence issues directly
• Keep fixes scoped to the spec and the discovered gaps
• Simplify when simplification improves clarity or removes redundant branches
• Preserve existing patterns unless the pattern itself is the problem
• Leave ambiguous, high-risk, or product-decision gaps as explicit follow-ups instead of guessing

Do not pad the implementation with speculative fallbacks just to feel safe.

6. Optional External Reviewer Pass

Use when Implementation Mode has local git changes or a PR and the user asks for an external/bot review, a second pass, or shipping readiness.

Run this after mapping the work to the source of truth, not before.

Prefer this repo's review path: an advisory external reviewer (e.g. the codex-pr review loop / codex/AGY) run over the branch or the current diff. Follow that skill's invocation and budget-aware stopping rules; scope the review to the changed surface when a focused pass is enough.

Treat findings as advisory:

• fix actionable, correct findings
• reject incorrect findings with a short rationale
• defer product or ambiguous findings explicitly
• keep the authoritative source of truth above the reviewer's advice
• if the reviewer is unavailable, unauthenticated, hung, or rate-limited, record that and continue

7. Verify Proportionately

• Re-read touched files and confirm the checklist is more complete than before
• Run narrow verification that matches the change and the repo policy
• Prefer targeted tests or focused checks over blanket builds unless the user or repo policy requires broader verification

For plan-only changes, verify that the revised artifact is clearer, more executable, and easier to test than before.

8. Report Clearly

Present results in this order:

1. Findings that mattered
2. Fixes applied
3. Remaining risks, open questions, or deferred gaps

When reporting findings, prioritize:

• What was missed
• What was incorrect
• What could be simplified
• What you changed to close the gap

Use file references whenever they add precision.

For plan-only work, report with:

1. gaps or ambiguities found
2. edits or comments added to the plan/issue/spec
3. remaining open decisions before implementation

Tooling Guidance

• If the source of truth is a GitHub issue or PR, use GitHub tooling or gh
• If the source is a Linear ticket, use Linear tooling
• If the source is a local spec, prompt, or design artifact, read it directly
• If reviewing an implementation diff and an advisory external reviewer is available (e.g. the codex-pr review loop / codex/AGY), use it as a second pass when requested or when shipping-readiness risk justifies it
• If current best practices or external behavior matter and may have changed, research before concluding

Do not anchor the workflow to one tracker. The skill is driven by the spec, not by GitHub.

Example Requests

• Review this implementation plan before we build it. Tighten the scope, simplify it, and patch the issue text.
• Read this issue draft, find what's ambiguous or missing, and leave it in an executable state.
• Review what the dev built against this PRD and fix anything clearly missing or overcomplicated.
• Compare this implementation to the acceptance criteria below, find what was missed, and patch the gaps.
• See this ticket and the current diff. Give feedback, simplify where needed, and fix the obvious misses.