extraction-plan.json

extraction-plan.json defines the ordered sequence in which modules should be extracted from the legacy system. It captures dependencies between modules, risk levels, duration estimates, and acceptance criteria for each phase.

Full Example

{
  "phases": [
    {
      "phase": 1,
      "name": "Core Accounting",
      "duration_weeks": 13,
      "contexts": ["Accounts", "Tax"],
      "risk": "medium",
      "dependencies": [],
      "acceptance": "68 parity tests passing, <5% behavior deviation"
    },
    {
      "phase": 2,
      "name": "Stock Management",
      "duration_weeks": 10,
      "contexts": ["Stock", "Warehouse"],
      "risk": "high",
      "dependencies": ["Accounts"],
      "acceptance": "Stock valuation parity verified, batch/serial tracking functional"
    },
    {
      "phase": 3,
      "name": "Transaction Layer",
      "duration_weeks": 8,
      "contexts": ["Selling", "Buying"],
      "risk": "medium",
      "dependencies": ["Accounts", "Stock"],
      "acceptance": "Order-to-invoice lifecycle functional with parity tests"
    }
  ],
  "sequencing": [
    {
      "extract": "Mode of Payment",
      "before": "Payment Entry",
      "reason": "No external dependencies"
    },
    {
      "extract": "Tax Calculator",
      "before": "GL Entry",
      "reason": "GL depends on tax computation"
    },
    {
      "extract": "Account Master",
      "before": "Journal Entry",
      "reason": "Journal Entry references account chart"
    },
    {
      "extract": "GL Entry",
      "before": "Sales Invoice",
      "reason": "Invoice posting creates GL entries"
    }
  ]
}

Field Reference

phases Array

Each entry defines a migration phase:

Field	Type	Required	Description
phase	number	Yes	Phase sequence number (1-based)
name	string	Yes	Human-readable phase name
duration_weeks	number	Yes	Estimated duration in weeks
contexts	string[]	Yes	Bounded contexts to extract in this phase
risk	string	Yes	Risk level: "low", "medium", "high"
dependencies	string[]	Yes	Phases/contexts that must be completed first
acceptance	string	Yes	Criteria that must be met to consider this phase done

sequencing Array

Fine-grained ordering constraints within or across phases:

Field	Type	Required	Description
extract	string	Yes	Module to extract
before	string	Yes	Module that depends on the extracted module
reason	string	Yes	Why this ordering is required

Designing Phases

Phase Sizing

Each phase should cover one bounded concern. Guidelines:

Duration	Typical Scope
2-4 weeks	Single small context (5-15 entities)
6-10 weeks	Single medium context (15-40 entities)
10-16 weeks	Large context or multiple small contexts

Risk Assessment

Risk Level	Characteristics
Low	Well-isolated module, few dependencies, strong existing tests
Medium	Some cross-module dependencies, needs ACL, moderate test coverage
High	Deep framework coupling, shared controllers, many implicit dependencies

Acceptance Criteria

Acceptance should be measurable and specific:

• Parity test counts with pass rates
• Behavior deviation thresholds
• Performance benchmarks if relevant
• Integration test requirements

Avoid vague criteria like “migration complete” or “works correctly.”

Sequencing Constraints

The sequencing array captures dependency ordering at the module level. An agent checking whether it can extract a module should:

1. Find the module in sequencing
2. Check if all entries where this module appears in before have their extract module completed
3. If any dependency is incomplete, the module cannot be safely extracted yet

Agent Behavior

Before extracting any module:

1. Check extraction-plan.json for the current phase
2. Verify all dependencies for that phase are complete
3. Check sequencing for module-level constraints
4. Refer to parity-tests.json for the acceptance criteria
5. After extraction, update migration-state.json with progress

Next Steps

• parity-tests.json — Behavior preservation tests
• migration-state.json — Progress tracking