fix-implementation-plan-drifts

Fix Implementation Plan Drifts

Overview

Implementation plans are living documents. When code ships, the plan should reflect what was built. This skill detects the gap and determines whether to update the plan or flag the code for review.

When to Use

• A feature PR merged that implements part of a plan
• A Jira epic moved to Done but the plan wasn't updated
• Reviewing a plan before starting new work on top of it
• Code review flagged something that contradicts the plan

How to Start

1. Ask the user: verify a specific plan or all plans?
2. Ask which repos to verify against. Plans often span multiple repositories. The user can choose the current repo, a specific repo, or all repos referenced in the plan. Default to the current repo.
3. Use the cross-repo map from the gcp-hcp-architecture skill to identify which repo owns each component. If the plan references repos beyond the user's selection, list them and ask if the user wants to include them.

What Is Drift

Drift is the gap between what the plan says and what the code does. It goes both ways:

• Plan drifted from code — the code evolved but the plan was never updated. Fix: update the plan.
• Code drifted from plan — the implementation deviated from the planned design, especially when it breaks architectural invariants or core principles. Fix: flag for team review.

Focus on meaningful differences — API contracts, behavior, architecture. Don't nitpick formatting or stylistic choices.

Drift Categories

For each plan, verify these against actual code:

API surface — types, structs, or fields don't match actual definitions. Grep for every type and field mentioned. Compare names, tags, and markers. (e.g., plan references GCPNetworkSpec but code renamed it to GCPNetworkConfig)

Behavior — controller reconciliation logic, ownership patterns, or data flow differ from actual code. Read the actual reconcilers. (e.g., plan describes credentials managed in HO layer but code manages them in CPO)