shynlee04/hivemind-plugin/cross-cutting-change-mgmt

Cross-Cutting Change Management

Iron Law

Changes spanning multiple layers MUST follow ordered governance.
A test written after implementation is a description, not a guard.

Overview

Govern changes that span multiple architectural layers or frameworks. When a feature change simultaneously affects test infrastructure, interface contracts, and deep module logic — or when migrating behavior across framework boundaries — standard edit workflows fail because they do not account for lifecycle impacts, actor/consumer dependencies, and ordering constraints.

This skill is framework-agnostic. It provides the methodology for ordering, impact analysis, and consumer tracing without depending on any specific framework's tooling or conventions. For framework-specific application, see the terminology map in references/terminology-map.md.

The methodology rests on three pillars:

1. Red-first verification — failing tests prove the change is real, not cosmetic. A test that passes before implementation is either wrong or redundant.
2. Ordering governance — interface contracts stabilize before deep modules change before consumers adapt. Inverting this order causes contract drift and broken consumers.
3. Consumer impact tracing — every change radiates outward. Untracked consumers become broken consumers.

When to Use

Use this skill when ALL of the following apply:

• [ ] The change affects 2 or more layers (test layer + implementation layer; interface + deep module; or ≥2 framework domains)
• [ ] The change involves behavioral modification, not cosmetic refactoring
• [ ] Consumers (downstream modules, dependent services, external callers) exist and may be affected

Do NOT use this skill for:

• Single-layer changes, single-file edits, or cosmetic refactors — use standard TDD
• Framework-specific tool configuration — consult that framework's reference
• Code review or audit — use review skills

Entry Gate

Proceed only when:

• [ ] The scope boundary is declared: which layers are IN vs OUT
• [ ] At least one behavior contract, requirement, or bug reproduction is documented
• [ ] No implementation code has been written yet — revert if it has (for a true RED cycle)
• [ ] The framework context is identified (GSD, BMAD, Hivemind, or other)

If requirements are ambiguous, stop and clarify before proceeding. Cross-cutting changes made against unclear requirements produce changes that are hard to reverse.

Core Workflow

Follow this sequence. Do not skip phases — the ordering is the governance.

Scan → Classify → Impact Analysis → Red-First → Implement (by ordering) → Verify → Handoff

Phase 1: Scan — Detect Affected Files

Identify every file in the blast radius. Use search tools to find all references to the target symbol, module, or interface.

Approach:

1. Search for the target symbol across the entire project
2. Map file dependencies — who imports/requires the affected module
3. Check for indirect consumers via re-exports or facade modules
4. Record the full file list — do not filter or assume files are safe

Gate: The scan must identify ≥2 layers. If only one layer is affected, this is not a cross-cutting change.

Phase 2: Classify — Assign Each File to a Layer

Classify every scanned file into exactly one layer. The specific layer names vary by framework — use the terminology map in references/terminology-map.md to identify the correct taxonomy for your framework.

Universal layer taxonomy:

Record the classification. Do not assign a file to multiple layers — pick the primary role.

Phase 3: Impact Analysis — Identify Lifecycle Effects

For each affected file, answer:

1. Which actors use this? (users, services, agents, tools, external systems)
2. What breaks if this changes? (compile-time, runtime, behavioral, contract)
3. What must change in lockstep? (paired interfaces, shared contracts, tight coupling)
4. What tests detect regressions? (existing tests, new tests needed)

Document impacts. A missed consumer is a broken consumer.

Gate: All actors and lockstep changes must be identified before implementation begins.

Phase 4: Red-First Protocol

Before writing ANY implementation code:

1. Write failing tests for the test-layer files identified in Phase 2
2. Verify the failure reason — the test must fail due to the missing or changed behavior, not due to syntax errors, import errors, or test setup issues
3. Record RED evidence — capture test output showing the failure
4. If a test passes before implementation → STOP. Either:

• The change already exists (scope error)
• The test does not test the right thing (rewrite it)
• Heavy mocking is hiding real behavior (reduce mocking)

Gate: Every test-layer file must show RED before implementation. No exceptions.

Read references/philosophy.md for the reasoning behind this non-negotiable requirement.

Phase 5: Implement — Change by Ordering

Implement changes in this locked order:

1. Interface / Contract changes first — public APIs, types, contracts, route signatures
2. Deep Module / Implementation changes second — business logic, services, algorithms
3. Config / Environment changes — in parallel with deep modules (low risk)
4. Test updates third — modify tests to match new behavior AFTER deep modules stabilize
5. Consumer / Downstream updates last — dependent services, plugins, external callers

Why this order: Interface contracts define the public face. Deep modules implement against contracts. Changing deep modules first causes contract drift. Consumers adapt last because their integration surface depends on stable interfaces.

After each tier, verify correctness before advancing.

Gate: Never carry tier-1 breakage into tier-2. Fix within the current tier first.

Phase 6: Verify — Honesty Check

After GREEN (all tests pass), verify the tests are honest:

• [ ] Do any tests pass only because of heavy mocking that suppresses real behavior?
• [ ] Would tests fail if mocks were replaced with real implementations?
• [ ] Are there tests that assert mock call counts but never verify real side effects?
• [ ] Does at least one real (non-mocked) test exercise the changed behavior end-to-end?

A test suite that passes entirely through mocks is not evidence of correctness.

Gate: At least one real test must exercise the changed behavior end-to-end.

Phase 7: Handoff — Produce Change Packet

Document the change for downstream consumers and future maintainers:

• What changed — summary of the behavioral modification
• Which layers were affected — with the classification from Phase 2
• Which files were changed — full list with per-file description
• RED evidence — test failure output from Phase 4
• GREEN evidence — test passing output from Phase 6
• Rollback steps — how to reverse the change in the correct order
• Consumer impact — which downstream consumers were affected and how

Rollback Governance

Every cross-cutting change must include rollback steps. Rollback reverses in the opposite order of implementation:

1. Revert consumer changes first (they depend on the change)
2. Revert test changes (they assert the new behavior)
3. Revert deep module changes
4. Revert interface changes last (consumers may depend on old interface)

Rollback must be testable — run the pre-change RED tests after rollback to verify the system returned to its prior state.

Anti-Patterns

Self-Correction

When RED phase fails for the wrong reason

Detection: Test fails with a compile error, type error, or import error — not a behavior/assertion failure. Recovery: The RED failure must prove the behavior is MISSING, not that code does not compile. Fix the test setup (imports, types, mocks) until it compiles but FAILS on the assertion. If the test passes after fixing setup, the change already exists — re-check scope.

When a consumer layer is missed in the scan

Detection: After deployment, a downstream service breaks because it depended on the changed interface. Scan only found 2 layers but there should have been 3+. Recovery: Re-run scan with broader patterns. Check dependency trees. Check for indirect consumers via re-exports or facade modules. If consumer is in a different repository, document the cross-repo impact.

When ordering rules are violated mid-implementation

Detection: Implementation changes were committed before interface contract changes, causing drift. Recovery: Revert to pre-change state. Re-execute from Phase 4 (Red-First) following the locked order. Document the violation in the handoff packet.

When tests deceive through mocking

Detection: Multiple tests assert expect(mockFn).toHaveBeenCalled() but none verify real side effects. Removing mock implementations breaks tests. Recovery: Add at least one integration test with real dependencies. If integration test is impractical (external service, cost, flakiness), document the limitation in the handoff packet as a known risk. Never claim PASS if all tests are mock-only.

Verification Checklist

Before declaring a cross-cutting change complete: