agentic-coding-review

name	agentic-coding-review
description	Use after a Superpowers implementation plan finishes to compare the result against the original design spec, fix clear in-phase gaps, and update roadmap follow-up phases.
argument-hint	[optional: plan path or spec path]

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:

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:

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.