agentic-coding-review

# Agentic Coding Review Use this skill after an implementation plan finishes through `superpowers:executing-plans`, `superpowers:subagent-driven-development`, or an agentic wrapper. The review compares actual work against the original design spec before the work is treated as complete. ## Purpose Close the loop between design intent and implementation result. Identify clear misses from the current phase, fix small safe gaps directly, and push legitimate later work back into the roadmap instead of expanding a completed plan indefinitely. ## Source Spec Resolution Resolve the original design spec from the implementation plan header. Recognize these fields: ```text Design spec: Spec: Original spec: Spec ID: ``` If the plan lacks a source spec reference, inspect nearby plan content and recent git history. If the source spec still cannot be resolved, report the blocker instead of inventing a source. Preserve source spec metadata when making review-driven follow-up changes. Do not remove or overwrite the original `Design spec:` or `Spec ID:` links; Agentic Memory uses those links to connect review, revision, and plan summaries back to the source design. ## Review Inputs Read only the context needed to make the review defensible: - Original design spec goals, non-goals, scope, acceptance criteria, and quality gates. - Implementation plan tasks and checkboxes. - Current git diff and recent commits on the plan branch. - Test and verification output when available. - Relevant roadmap phase status and artifact links when the work belongs to a roadmap. ## Finding Categories Classify findings as: - `Must fix in current phase`: a clear miss from the current design spec or acceptance criteria. - `Accept as intentional`: consistent with non-goals, explicit tradeoffs, or user-approved scope. - `Follow-up phase`: real work, but outside the current phase and better represented as a later roadmap phase. ## Fix Policy When a `Must fix in current phase` item is small, low-risk, and clearly implied by the approved spec, fix it directly and run focused verification. If the gap requires new design work, changes phase boundaries, or would expand the implementation beyond the approved spec, stop and ask for a new spec or roadmap update. Do not silently convert a current-phase miss into a follow-up phase just to declare the plan done. ## Roadmap Updates This skill updates a roadmap when: - The implementation result changes the status or evidence for a roadmap-tracked phase. - A gap should become a later phase. - A planned phase needs a clarified dependency, acceptance note, or artifact reference based on execution evidence. The skill should not reorder the whole roadmap for ordinary bug fixes or unrelated discoveries. ## Output Report: - Source spec used. - Plan or branch reviewed. - Findings by category. - Direct fixes made, if any. - Verification run and result. - Roadmap updates made or explicitly skipped. If there are no findings, say that clearly and list any residual test or review risk. ## Structured Result Contract For unattended Phase 6.5A runs, write a structured review result that can be validated mechanically and consumed by `codex-agentic` automation: ```yaml kind: agentic-coding-review-result schema_version: v1 phase_id: phase-002-business-asset-derivation plan_ref: "<repo-relative-plan-ref-from-superpowers>" source_spec_ref: docs/superpowers/specs/2026-05-24-current-phase-design.md result: no_gap gaps: [] blocked_reason: null ``` Supported gap classes include: - `no_gap` - `in_phase_gap` - `out_of_phase_or_ambiguous_gap` Use `allowed_auto_fix` only when the gap is clearly in phase, required by the confirmed Spec and plan, and does not change business semantics. Out-of-phase, ambiguous, requirement-changing, migration, deployment, release, approval, and cross-module contract gaps must block automation. Do not parse human-readable codex-agentic stdout or HUD text as a review decision contract.