engineering-plan-review

name	engineering-plan-review
description	Use when reviewing implementation plans, architecture plans, refactor plans, migration plans, technical proposals, and APIVR Phase 2 blueprints for engineering soundness, risk, module boundaries, dependency direction, testability, operational readiness, and source-of-truth alignment before code changes begin.
activation	Activate when the description trigger applies to the current task.
required_inputs	Task request, relevant repository context, constraints, and authority dependencies.
required_outputs	Skill-specific artifact, verification evidence, canonical verdict, and next action.
authority_dependencies	00_start_here/SOURCE_OF_TRUTH.md; 10_governance/APIVR_EXECUTION_LIFECYCLE.md; 10_governance/source_of_truth/Elite_Build_Goals_v3.md.
evidence_requirements	Executed checks or an honest Unknown, Not Run, or Blocked state for every material claim.

Engineering Plan Review

Use this skill after skills/writing-plans/SKILL.md drafts a plan and before APIVR Phase 3 implementation begins.

Do not approve a plan that cannot be executed and verified without inventing missing technical decisions.

Review Order

1. Scope: objective, non-goals, acceptance criteria, and preserved behavior.
2. Architecture: source of truth, module boundaries, dependency direction, and data flow.
3. Testability: failing tests, characterization tests, contract tests, or evidence-first substitutes.
4. Risk: security, data integrity, migration, performance, cost, release, and rollback.
5. Operations: logs, metrics, health, retries, backfill, and incident recovery.
6. External integration gate: for provider callbacks, webhooks, OAuth/Auth redirects, cron routes, payments, email/SMS providers, or Preview/Production env splits, confirm skills/external-integration-launch-gate/SKILL.md was applied and route contracts exist.
7. 20 Pass Protocol: for high-stakes plans, agent handoffs, source-file precise remediation, release instructions, or forensic audit outputs, confirm skills/20-pass-protocol/SKILL.md was applied or a compressed pass is justified.
8. Execution: exact files, commands, sequence, and stop conditions.

Decision Flow

flowchart TD
  A["Plan ready for review"] --> B{"Zero placeholders?"}
  B -- "No" --> X["Return to writing-plans"]
  B -- "Yes" --> C{"Architecture source of truth named?"}
  C -- "No" --> X
  C -- "Yes" --> D{"Test/evidence path proves behavior?"}
  D -- "No" --> X
  D -- "Yes" --> E{"Risk and rollback fit tier?"}
  E -- "No" --> F["Escalate APIVR tier or narrow scope"]
  E -- "Yes" --> G["Approve for APIVR Phase 3"]

Review Findings

Use this format:

Finding:
Severity: Blocking / Important / Advisory
APIVR phase affected:
Evidence state:
Required correction:

Worked Example

Scenario: A plan adds OAuth login.

• Blocking finding: plan names provider setup but omits callback validation and state/nonce checks.
• APIVR effect: security evidence remains Unknown; release gate C fails.
• Required correction: add auth threat model, tests for invalid state, provider error handling, secret storage, and rollback to password login.
• Verdict: return to Phase 2 until the evidence path is complete.

Scenario: A plan adds a Stripe webhook.

• Blocking finding: plan tests the route handler directly but omits deployed provider delivery through middleware and deployment protection.