Migration impact map across services

For: Staff engineer or platform lead planning a framework, database or shared-library migration

Pattern: Hierarchical decompositionNeeds a connectorDesigned for 30 to 800 agents

The pain today

A breaking upgrade touches modules owned by many teams. The plan is built from text search and memory, so the surprises arrive mid-migration, in the services nobody listed.

The ask

We are moving off the old version of our shared API client. I attached the migration guide and connected the repositories. Map every service and module that is affected, what kind of change each one needs and what order they must go in, and show the lines that prove it.

Plain words, as you would say it to a colleague. Edit it to fit your case before you send it.

What you attach or connect

  • Migration guide and list of breaking changes
  • Repositories through source control, at a pinned commit
  • Service ownership map
  • Dependency graph between services, if one exists

The unit of work

One worker task per one module against the breaking-change list.

Why a swarm fits

The goal splits cleanly: estate, service, module, call site. Each leaf needs only its own files and the breaking-change list, and each level can be checked before it rolls up.

Not for

A change confined to one service: one strong model with the repository open is faster and cheaper.

The decision tree

6 typed decisions, each with an action for every answer

At fixed moments in a run, the engine puts one narrow question to a decision model. The decision model never writes text: it answers yes or no with a probability, picks from listed options, or gives a score, about a small slice of the material. The engine then does exactly what this tree says, which is what makes the run auditable. The thresholds are the template's design values, not measured results.

  1. Planner, while planning

    Split or keep serialYes or no, with a probability

    While planning

    Does this service contain enough separately owned modules importing the shared client that scanning them in parallel beats one pass over the service?

    Sees only: The service's module list with owners and import counts for the shared client

    Why: Avoids paying coordination cost on small services that one worker can read whole.

    • Yes: 0.60 or higherthenSplit the work
    • Unsure: 0.30 up to 0.60thenKeep serial
    • No: below 0.30thenKeep serial
  2. Scope checkYes or no, with a probability

    Before work starts on a unit

    Does this module import or re-export the library being migrated, directly or through an internal wrapper named on the wrapper list?

    Sees only: The module's import statements and the list of internal wrappers

    Why: Most modules never touch the library; skipping them is where the width becomes affordable.

    • Yes: 0.60 or higherthenAccept
    • Unsure: 0.20 up to 0.60thenAccept
    • No: below 0.20thenSkip this unit
  3. After workers, the judge checks

    Evidence checkYes or no, with a probability

    After a worker answers

    Does the cited line call the changed function in the way the breaking-change entry describes, for example passing the removed argument or reading the old return shape?

    Sees only: The cited lines with a little surrounding code, and one breaking-change entry

    Why: A false hit wastes an owner's time; a loose match hides the real work.

    • Yes: 0.85 or higherthenAccept
    • Unsure: 0.50 up to 0.85thenEscalate to a strong model
    • No: below 0.50thenReject and retry
  4. Run control, between rounds

    Retry or stopYes or no, with a probability

    After a rejection or low confidence

    The first scan called this module clean but the sampled re-check found a usage: do the two results truly disagree about the same file?

    Sees only: The two scan results for the module and the file paths each one read

    Why: One overturned clean result means the cheap scan is missing a usage style, so the service is re-read properly.

    • Yes: 0.60 or higherthenEscalate to a strong model
    • Unsure: 0.30 up to 0.60thenEscalate to a strong model
    • No: below 0.30thenContinue
  5. Another round?Yes or no, with a probability

    Between rounds

    Is every module of this service either resolved with cited lines or listed as a blind spot, so the service can roll up?

    Sees only: The service's module status table

    Why: Stops a half-scanned service from entering the migration order as if it were known.

    • Yes: 0.85 or higherthenStop
    • Unsure: 0.50 up to 0.85thenContinue
    • No: below 0.50thenContinue
  6. Accountable person, before anything is settled

    Person decidesYes or no, with a probability

    Before anything is reported as settled

    Does this service's change list include a change to a public interface, a data schema or a module with no listed owner?

    Sees only: The service's rolled-up change list and its ownership map row

    Why: Order, freeze windows and unowned code are the platform lead's calls.

    Accountable: The platform lead owns the order, the freeze windows and the decision to start; each owner confirms their service's list.

    • Yes: 0.40 or higherthenAsk a person
    • Unsure: 0.15 up to 0.40thenAsk a person
    • No: below 0.15thenAccept

The fleet: who does what

Model tiers by role, not brands: you choose the models. Strong reasoning models plan and reconcile, small fast models do the wide work, and the judge is a decision model from a different family, so it does not share the workers' blind spots.

  1. Planner

    A strong reasoning model builds the tree from services down to modules and decides what each level must prove.

    Decisions here:1. Split or keep serial2. Scope check

  2. Workers

    Small fast workers from an open-weight family each scan one module for affected usages and cite file and line.

    Designed for 30 to 800 agents, one worker task per one module against the breaking-change list. Each worker receives only its own unit.

  3. Judge, from a different model family

    A decision model from a different family checks each cited line really uses the changed behaviour.

    Decisions here:3. Evidence check

  4. Reconciler

    A strong reasoning model rolls leaves up into per-service change lists, ordering constraints and open questions.

    Decisions here:4. Retry or stop5. Another round?

  5. Accountable person

    The platform lead owns the order, the freeze windows and the decision to start; each owner confirms their service's list.

    Decisions here:6. Person decides

Checked before anything is accepted

  • Every affected usage cites file, line and the breaking change it matches
  • Modules reported clean are sampled by a second worker from another family
  • A service rolls up only when all its modules are resolved or listed as unknown
  • Dynamic or generated usages the scan cannot see are listed as blind spots

What comes back

  • Impact map by service and owner
  • Change type per module with cited lines
  • Suggested migration order with the dependency behind each step
  • Blind spots and modules with no owner

What to measure

  • Affected modules found during migration that the map missed
  • False positives per service
  • Planning time against the previous migration
  • Cost per module scanned

Names of measures only. No result is claimed for this template.

Templates open in the workspace chat with the ask filled in. Nothing runs until you send it.

Get early accessSign in to use

Dependency and licence audit across a monorepo

For: Engineering lead or open-source compliance owner preparing a release, a sale or a customer audit

A monorepo pulls in a very long list of direct and transitive packages, each with its own licence text.

Pattern: Map, verify, reduceNeeds scale5 decisionsDesigned for 40 to 600 agents

Test case tournament for a module that must not break

For: Quality lead or engineer owning a payment, pricing or permissions module with thin tests

The module that must not break has happy-path tests only.

Pattern: TournamentNeeds a connector6 decisionsDesigned for 20 to 300 agents

Design review panel for an architecture proposal

For: Engineering manager or architect taking a design document to review before build starts

Design reviews depend on who shows up.

Pattern: Specialist panelNeeds live models5 decisionsDesigned for 4 to 16 agents