Domain Model Refactoring Impact Analysis Prompt

This prompt is for domain architects and engineering leads planning a refactor of aggregates, bounded contexts, or domain events. It produces a structured impact map that identifies affected contexts, APIs, events, data migrations, and downstream consumers. Use it before committing to a refactoring plan to surface hidden coupling, sequencing risks, and migration complexity that might otherwise surface mid-implementation.

This is a design-time analysis tool, not a runtime migration executor. It assumes you have a documented or well-understood current-state domain model. If your model exists only in tribal knowledge, run a context map or glossary extraction prompt first. The prompt works best when you provide concrete artifacts: existing context maps, event schemas, API contracts, aggregate definitions, and known integration points. Vague inputs produce vague impact maps. For high-risk refactors in regulated domains, always pair the output with human architecture review before committing to implementation.

Do not use this prompt for greenfield design where no current-state model exists, for runtime data migration scripting, or for performance profiling of existing systems. It is not a replacement for static analysis tools that inspect code dependencies. If you need to discover bounded contexts from legacy code, use the Bounded Context Discovery from Legacy Code prompt instead. If you need to validate a specific aggregate design, use the Aggregate Root Design Validation Prompt. This prompt is specifically for understanding the blast radius of a planned change before you make it.

This prompt template is designed to be dropped directly into your AI orchestration layer. It instructs the model to act as a domain architect and produce a structured impact analysis for a planned refactoring. The template uses square-bracket placeholders for all dynamic inputs, such as the model to refactor, the reason for the change, and the system's current context map. Before using it, ensure you have gathered the necessary source materials: your current bounded context definitions, aggregate designs, and a catalog of known domain events and API contracts. The quality of the output depends heavily on the specificity of the inputs you provide.

textCopy
You are a domain architect specializing in Domain-Driven Design (DDD). Your task is to perform a rigorous impact analysis for a proposed domain model refactoring. You will be given the current state of the model, the proposed change, and the system's context map. Your analysis must be precise, actionable, and identify all downstream consequences.

**INPUTS**
- **Refactoring Target:** [TARGET_AGGREGATE_OR_CONTEXT]
- **Refactoring Intent:** [REFACTORING_DESCRIPTION] (e.g., "Split the Customer aggregate into Customer and CustomerBillingProfile to reduce contention.")
- **Current Model Snapshot:** [CURRENT_DOMAIN_MODEL_DESCRIPTION]
- **Context Map:** [CONTEXT_MAP_DESCRIPTION]
- **Known Domain Events:** [LIST_OF_DOMAIN_EVENTS]
- **Known API Contracts:** [LIST_OF_API_CONTRACTS]

**CONSTRAINTS**
- [CONSTRAINTS] (e.g., "Must maintain backward compatibility for the GET /customers/{id} endpoint.")

**OUTPUT_SCHEMA**
Produce a JSON object with the following structure. Do not include any text outside the JSON object.
{
  "impact_map": {
    "affected_contexts": [
      {
        "context_name": "string",
        "impact_type": "BREAKING_CHANGE | ADAPTATION_REQUIRED | NO_IMPACT",
        "rationale": "string",
        "required_changes": ["string"]
      }
    ],
    "affected_apis": [
      {
        "api_identifier": "string",
        "impact_type": "BREAKING_CHANGE | DEPRECATION | NO_IMPACT",
        "migration_notes": "string"
      }
    ],
    "affected_events": [
      {
        "event_name": "string",
        "impact_type": "SCHEMA_CHANGE | PAYLOAD_CHANGE | DEPRECATION | NO_IMPACT",
        "new_schema_suggestion": "string"
      }
    ],
    "data_migrations": [
      {
        "source": "string",
        "target": "string",
        "migration_type": "SCRIPT | ETL | EVENT_REPLAY",
        "complexity": "LOW | MEDIUM | HIGH",
        "description": "string"
      }
    ]
  },
  "risk_assessment": {
    "overall_risk_score": "LOW | MEDIUM | HIGH | CRITICAL",
    "key_risks": ["string"],
    "rollback_complexity": "SIMPLE | COMPLEX | IMPOSSIBLE"
  },
  "sequencing_guidance": {
    "recommended_phases": [
      {
        "phase": "number",
        "description": "string",
        "contexts_involved": ["string"],
        "validation_criteria": "string"
      }
    ],
    "parallelizable_work": ["string"]
  }
}

**RISK_LEVEL:** [RISK_LEVEL] (e.g., HIGH - This is a core domain refactor in a financial system. Flag any risk of data inconsistency or double-billing.)

To adapt this template, start by replacing the placeholders in the INPUTS and CONSTRAINTS sections with your specific details. The OUTPUT_SCHEMA is designed to be parsed by your application code, so resist the urge to simplify it into free text unless you are only doing a one-off analysis. For high-risk domains, as indicated by the [RISK_LEVEL] placeholder, you should add a post-processing step in your harness that flags any CRITICAL overall risk score or IMPOSSIBLE rollback complexity for immediate human review before the analysis is shared with the team. The sequencing_guidance is the most valuable part for planning; ensure your evaluation tests check that the phases are logically ordered and have clear, testable validation criteria.

This prompt is designed to be called programmatically as part of a refactoring planning pipeline, not as a one-off chat interaction. The implementation harness should treat the prompt as a deterministic analysis function: provide the structured inputs, parse the structured output, validate it against the expected schema, and route the result to the appropriate review queue. Because the output includes risk scores and migration sequencing, downstream automation (such as ticket creation or CI pipeline gating) depends on correct parsing. The harness must handle both successful analyses and failure modes where the model returns incomplete impact maps, hallucinated context names, or confidence scores that don't match the evidence provided.

Wire the prompt into an application using a typed function signature. Accept a RefactoringProposal input object containing the target aggregate or context name, the proposed change description, a current context map (as structured JSON or a textual description), and a list of known domain events and integration points. Call the LLM with the prompt template, passing these fields into the [INPUT] placeholder. Parse the response into an ImpactAnalysis schema that includes: an array of affected contexts with coupling type and risk score, an array of affected APIs with breaking-change flags, an array of affected domain events with migration notes, a data migration checklist, a sequenced refactoring order, and an overall risk level. Use a schema validation library (such as Pydantic or Zod) to enforce field types, required fields, and enum constraints on risk levels (LOW, MEDIUM, HIGH, CRITICAL). If validation fails, retry once with the validation errors appended to the prompt as [CONSTRAINTS] feedback. If the second attempt also fails, escalate to a human architect for manual review rather than looping indefinitely.

For high-risk refactorings where the output risk level is HIGH or CRITICAL, route the impact analysis to a human approval queue before any automated actions are taken. Log every invocation with the input proposal, the raw model response, the parsed output, validation results, and the final disposition (accepted, retried, escalated). Store these logs in a refactoring decision record for auditability. Choose a model with strong structured output capabilities and a context window large enough to hold the full context map plus the analysis output. Avoid using this prompt with small or instruction-untuned models that are likely to hallucinate context names or skip required sections. If your context map is too large for a single prompt, preprocess it by extracting only the contexts within two hops of the target aggregate and summarizing distant contexts before passing them to the model.