@valentia-ai-skills/framework 2.0.6 → 2.0.8

package/skills/global/legacy-redevelopment-planner/SKILL.md

@@ -0,0 +1,622 @@
+---
+name: legacy-redevelopment-planner
+description: Reads the intelligence package generated by the codebase-legacy-intelligence skill and produces a comprehensive, sprint-ready redevelopment plan for rebuilding the application in a modern tech stack. Covers tech stack selection, architecture design, phased migration strategy, module dependency ordering, risk assessment, data migration plan, API compatibility layer, testing strategy, and sprint-level task breakdowns. Use this skill whenever someone wants to: plan a rewrite of a legacy app, migrate from one framework to another (e.g., .NET MVC to React, jQuery to React, monolith to microservices), create a development roadmap from legacy intelligence files, plan a modernization effort, estimate effort for rebuilding an application, or decide on a migration strategy (strangler fig, big bang, parallel run). Also trigger when someone says things like "plan the rebuild", "how should we rewrite this", "migrate this to React", "modernize this app", "create a development plan from the scan", "what would it take to rebuild this", or "plan the redevelopment". This skill expects the output from codebase-legacy-intelligence as input — specifically the MASTER_SKILL.md, module SKILL.md files, BUSINESS_RULES.md, API_REGISTRY.md, DATA_MODELS.md, DEPENDENCIES.md, and REPRODUCTION_GUIDE.md.
+version: 1.0.0
+scope: global
+last_reviewed: 2026-04-02
+---
+
+---
+name: legacy-redevelopment-planner
+description: >
+  Reads the intelligence package generated by the codebase-legacy-intelligence skill and produces
+  a comprehensive, sprint-ready redevelopment plan for rebuilding the application in a modern tech
+  stack. Covers tech stack selection, architecture design, phased migration strategy, module
+  dependency ordering, risk assessment, data migration plan, API compatibility layer, testing
+  strategy, and sprint-level task breakdowns. Use this skill whenever someone wants to: plan a
+  rewrite of a legacy app, migrate from one framework to another (e.g., .NET MVC to React, jQuery
+  to React, monolith to microservices), create a development roadmap from legacy intelligence files,
+  plan a modernization effort, estimate effort for rebuilding an application, or decide on a
+  migration strategy (strangler fig, big bang, parallel run). Also trigger when someone says things
+  like "plan the rebuild", "how should we rewrite this", "migrate this to React", "modernize this
+  app", "create a development plan from the scan", "what would it take to rebuild this", or
+  "plan the redevelopment". This skill expects the output from codebase-legacy-intelligence as input
+  — specifically the MASTER_SKILL.md, module SKILL.md files, BUSINESS_RULES.md, API_REGISTRY.md,
+  DATA_MODELS.md, DEPENDENCIES.md, and REPRODUCTION_GUIDE.md.
+---
+
+# Legacy Redevelopment Planner
+
+You are a senior technical architect and project planner. Your job is to read the intelligence package from a legacy codebase scan and produce a **production-grade redevelopment plan** — not a vague roadmap, but a concrete, phased, sprint-ready plan that a development team can execute from day one.
+
+## Philosophy
+
+Rewrites fail for predictable reasons: underestimating hidden business logic, wrong migration strategy, breaking changes in the API layer that downstream consumers can't absorb, data migration disasters, and scope creep from discovering undocumented behavior mid-build. Your plan must anticipate and address all of these. Every decision must be justified with evidence from the intelligence package.
+
+---
+
+## Step 0: Ingest the Intelligence Package
+
+Before planning anything, read and deeply understand the legacy application.
+
+### Locating the Intelligence Package
+
+The intelligence package can be in one of these locations:
+
+1. **Installed via CLI** (most common for team members): `.ai-skills/legacy-projects/{projectname}/`
+2. **Local scan output** (for the developer who ran the scan): `./{projectname}-intelligence/`
+3. **Custom path**: The user specifies where it is
+
+Check in this order:
+1. Ask the user: "Which legacy project are you planning for?" — get the project name
+2. Look for `.ai-skills/legacy-projects/{projectname}/` — if found, use it
+3. Look for `./{projectname}-intelligence/` — if found, use it
+4. If neither found, ask the user for the path
+5. Verify `manifest.json` exists in the folder — if not, this isn't a valid intelligence package
+
+### Required Files — Read in This Order:
+
+1. **manifest.json** — Project metadata, file inventory, statistics (read first to understand scope)
+2. **OVERVIEW.md** — Tech stack, architecture, project scale
+3. **MASTER_SKILL.md** — Full architecture, cross-cutting concerns, module map
+4. **BUSINESS_RULES.md** — Every extracted business rule (this is critical — rules drive effort estimation)
+5. **API_REGISTRY.md** — All endpoints exposed and consumed
+6. **DATA_MODELS.md** — Every entity, relationship, constraint
+7. **DEPENDENCIES.md** — External packages and service integrations
+8. **ENV_CONFIG.md** — Environment variables, feature flags, secrets
+9. **RISK_REPORT.md** — Tech debt, anti-patterns, security concerns
+10. **REPRODUCTION_GUIDE.md** — Rebuild order and dependency chain
+11. **Module SKILL.md files** — Read every file in `modules/*/SKILL.md` for per-module deep dive
+12. **Mermaid diagrams** — Read every `.mermaid` file in `diagrams/`
+
+If any file is missing, note it — it affects planning confidence. If BUSINESS_RULES.md or API_REGISTRY.md are missing, warn the user that estimation accuracy will be significantly reduced.
+
+Build a mental model of the entire application before proceeding. You need to understand:
+- What the app does (business domain)
+- How big it is (modules, endpoints, rules, entities)
+- What's tightly coupled vs loosely coupled
+- Where the complexity lives (which modules have the most business rules)
+- What external dependencies exist (APIs, services, databases)
+- What the risk hotspots are
+
+### Then Ask the User:
+
+1. **Target tech stack**: What do you want to rebuild in? (React, Next.js, Vue, Angular, etc. for frontend; Node/Express, NestJS, .NET Core, Python/FastAPI, etc. for backend; PostgreSQL, MongoDB, etc. for database). If they're unsure, recommend based on the application's needs.
+2. **Migration strategy preference**: Big bang rewrite, strangler fig (incremental), or parallel run? If unsure, you'll recommend.
+3. **Team size and composition**: How many developers? Frontend/backend split? Any expertise gaps?
+4. **Timeline constraints**: Is there a deadline? A budget ceiling?
+5. **Must-keep constraints**: Anything that must stay the same? (Same database? Same API contracts for external consumers? Same auth provider?)
+6. **Priority modules**: Which features are most critical to get right first?
+7. **Current pain points**: What's driving the rewrite? (Performance? Maintainability? Hiring? End of life for framework?)
+
+---
+
+## Step 1: Migration Strategy Assessment
+
+Based on the intelligence package and user inputs, recommend the right migration strategy. This is the most consequential decision in the plan.
+
+### Evaluate Each Strategy:
+
+**Big Bang Rewrite**
+- Suitable when: app is small-medium (<20 modules), team is strong, legacy app can be frozen during rebuild, no external API consumers that can't handle downtime
+- Risk: if it takes longer than expected, you're maintaining two codebases
+- Evidence to check: module count, coupling score from RISK_REPORT.md, external API consumer count from API_REGISTRY.md
+
+**Strangler Fig (Incremental)**
+- Suitable when: app is large, has external API consumers, can't freeze the legacy app, team needs to ship value during migration
+- Requires: an API compatibility layer or proxy that routes between old and new
+- Evidence to check: module dependency graph (which modules can be extracted independently?), API surface stability
+
+**Parallel Run**
+- Suitable when: the app is critical (healthcare, finance), correctness must be verified before cutover, you can afford to run both systems temporarily
+- Requires: traffic mirroring, output comparison tooling
+- Evidence to check: data sensitivity from BUSINESS_RULES.md, calculation complexity
+
+### Output: `MIGRATION_STRATEGY.md`
+
+```markdown
+# Migration Strategy
+
+## Recommendation: {strategy name}
+
+### Why This Strategy
+{Justify with specific evidence from the intelligence package — module count, coupling,
+external consumers, business rule complexity, team constraints}
+
+### Why Not the Alternatives
+{Explain why other strategies are less suitable for THIS specific project}
+
+### Strategy-Specific Plan
+{For strangler fig: which modules to extract first and why}
+{For big bang: how to manage the parallel development period}
+{For parallel run: how to set up traffic mirroring and comparison}
+
+### Risk Mitigation
+{Top 5 risks specific to this strategy + mitigation plan for each}
+```
+
+---
+
+## Step 2: Target Architecture Design
+
+Design the new architecture based on the legacy app's needs and the target tech stack.
+
+### Actions:
+1. Map each legacy module to its equivalent in the new stack
+2. Design the new module boundaries — this is a chance to fix coupling issues flagged in RISK_REPORT.md
+3. Define the new data model — migrate entities from DATA_MODELS.md, fixing any schema issues
+4. Design the API layer — maintain backward compatibility if external consumers exist
+5. Plan the authentication/authorization architecture
+6. Design the state management approach (frontend)
+7. Plan infrastructure (hosting, CI/CD, monitoring)
+
+### Output: `TARGET_ARCHITECTURE.md`
+
+```markdown
+# Target Architecture
+
+## Tech Stack
+| Layer | Technology | Justification |
+|-------|-----------|---------------|
+| Frontend | {framework} | {why this fits the app's needs} |
+| Backend | {framework} | {why} |
+| Database | {engine} | {why — migrate or keep?} |
+| Auth | {provider/approach} | {why} |
+| Hosting | {platform} | {why} |
+| CI/CD | {tool} | {why} |
+
+## Module Map: Legacy → New
+| Legacy Module | New Module(s) | Changes | Complexity |
+|---------------|--------------|---------|------------|
+| {old name} | {new name(s)} | {split/merged/renamed/restructured} | {low/med/high} |
+
+## Architecture Diagram
+{Mermaid diagram of the new system architecture}
+
+## Data Model Changes
+| Legacy Entity | New Entity | Changes | Migration Notes |
+|---------------|-----------|---------|-----------------|
+| {old} | {new} | {field changes, type changes, relationship changes} | {data transformation needed} |
+
+## API Compatibility
+| Legacy Endpoint | New Endpoint | Breaking Changes | Mitigation |
+|----------------|-------------|-----------------|------------|
+| {old} | {new} | {yes/no — what changed} | {adapter, versioning, deprecation period} |
+
+## New Architecture Patterns
+{What patterns will the new app use? Why are they better than the legacy patterns?}
+
+## Infrastructure
+{Hosting, deployment, monitoring, logging plan}
+```
+
+### Output: `diagrams/target-architecture.mermaid`
+
+---
+
+## Step 3: Effort Estimation
+
+This is where the intelligence package pays off. You have every business rule, endpoint, entity, and integration cataloged — use them for evidence-based estimation.
+
+### Estimation Method:
+
+For each module, count:
+- **Endpoints** (from API_REGISTRY.md) → each endpoint = base effort unit
+- **Business rules** (from BUSINESS_RULES.md) → each rule = complexity multiplier
+- **Entities** (from DATA_MODELS.md) → each entity = data layer effort
+- **External integrations** (from DEPENDENCIES.md) → each integration = integration effort + risk buffer
+- **State transitions** (from BUSINESS_RULES.md) → each state machine = high complexity
+- **Calculations/formulas** (from BUSINESS_RULES.md) → each formula = precision-critical effort
+
+### Complexity Scoring Per Module:
+
+```
+Simple module:    <5 endpoints, <10 rules, <3 entities, no external integrations
+Medium module:    5-15 endpoints, 10-30 rules, 3-8 entities, 1-2 integrations
+Complex module:   >15 endpoints, >30 rules, >8 entities, >2 integrations, state machines
+```
+
+### Output: `EFFORT_ESTIMATION.md`
+
+```markdown
+# Effort Estimation
+
+## Module-by-Module Breakdown
+
+### {Module Name}
+- **Endpoints**: {count} ({list key ones})
+- **Business Rules**: {count} ({note the complex ones})
+- **Entities**: {count}
+- **External Integrations**: {count}
+- **State Machines**: {yes/no}
+- **Complexity**: {simple/medium/complex}
+- **Estimated Effort**: {story points or developer-days}
+- **Risk Buffer**: {percentage — higher for modules with many cross-module rules or external integrations}
+- **Notes**: {anything that could increase/decrease effort}
+
+## Summary
+| Module | Complexity | Base Effort | Risk Buffer | Total |
+|--------|-----------|-------------|-------------|-------|
+| ... | ... | ... | ... | ... |
+
+## Total Project Estimate
+- **Base effort**: {sum}
+- **Risk buffer**: {sum of buffers}
+- **Data migration**: {separate estimate}
+- **Testing & QA**: {separate estimate — typically 30-40% of dev effort}
+- **DevOps & infrastructure**: {separate estimate}
+- **Grand total**: {sum}
+
+## Estimation Confidence
+{How confident are you in this estimate? What could blow it up?
+Reference specific unknowns from the intelligence package.}
+```
+
+---
+
+## Step 4: Phase Planning
+
+Break the redevelopment into phases. Each phase should deliver usable value and build on the previous one.
+
+### Phase Design Principles:
+1. **Dependency order first**: The REPRODUCTION_GUIDE.md has the build order — respect it
+2. **Foundation before features**: Auth, data layer, shared utilities come first
+3. **High-risk modules early**: Tackle complex/risky modules in early phases when there's time to course-correct
+4. **Quick wins for momentum**: Include at least one simple, visible module in Phase 1
+5. **API compatibility throughout**: If using strangler fig, each phase must maintain API compatibility
+
+### Output: `PHASE_PLAN.md`
+
+```markdown
+# Phase Plan
+
+## Phase 0: Foundation ({estimated duration})
+### Objective
+Set up the project scaffold, CI/CD, auth, database, and shared infrastructure.
+
+### Deliverables
+- [ ] Project repository initialized with {target stack}
+- [ ] CI/CD pipeline configured
+- [ ] Database schema migrated (see DATA_MIGRATION.md)
+- [ ] Authentication system implemented
+- [ ] Shared utilities and base components created
+- [ ] API compatibility layer / proxy set up (if strangler fig)
+- [ ] Monitoring and logging configured
+
+### Dependencies
+None — this is the foundation.
+
+### Risk
+{Phase-specific risks and mitigations}
+
+---
+
+## Phase 1: {Phase Name} ({estimated duration})
+### Objective
+{What this phase achieves}
+
+### Modules Included
+| Module | Key Features | Business Rules | Complexity |
+|--------|-------------|----------------|------------|
+| {module} | {features being built} | {rule IDs from BUSINESS_RULES.md} | {complexity} |
+
+### Deliverables
+- [ ] {Specific deliverable with acceptance criteria}
+- [ ] {Another deliverable}
+
+### Dependencies
+- Phase 0 complete
+- {Any specific modules or infrastructure needed}
+
+### Migration Steps (if strangler fig)
+{How to cut over this module from legacy to new — routing changes, data sync, etc.}
+
+### Risk
+{Phase-specific risks}
+
+---
+
+{Repeat for each phase}
+
+## Phase N: Cutover & Decommission
+### Objective
+Final migration, legacy system shutdown.
+
+### Deliverables
+- [ ] All traffic routed to new system
+- [ ] Data migration verified
+- [ ] Legacy system decommissioned
+- [ ] Post-migration monitoring period complete
+- [ ] Documentation updated
+
+## Timeline Summary
+| Phase | Duration | Modules | Cumulative Progress |
+|-------|----------|---------|-------------------|
+| 0 | {weeks} | Foundation | Infrastructure ready |
+| 1 | {weeks} | {modules} | {X}% of features live |
+| ... | ... | ... | ... |
+| N | {weeks} | Cutover | 100% |
+```
+
+---
+
+## Step 5: Data Migration Plan
+
+Data migration is where rewrites go to die. Plan it explicitly.
+
+### Output: `DATA_MIGRATION.md`
+
+```markdown
+# Data Migration Plan
+
+## Strategy: {approach}
+{Big bang migration / rolling migration / dual-write / event sourcing replay}
+
+## Schema Changes
+| Legacy Table | New Table | Transformation |
+|-------------|----------|----------------|
+| {old} | {new} | {field renames, type conversions, splits, merges, computed fields} |
+
+## Data Transformation Rules
+### {Transformation Name}
+- **Source**: {legacy table.column}
+- **Target**: {new table.column}
+- **Transform**: {exact transformation logic}
+- **Edge Cases**: {nulls, invalid data, orphaned records}
+
+## Migration Scripts
+{Description of scripts needed — what they do, what order to run them}
+
+## Verification
+| Check | Method | Acceptance Criteria |
+|-------|--------|-------------------|
+| Row counts match | {query comparison} | {exact match or known delta} |
+| Referential integrity | {FK validation} | {zero orphans} |
+| Business rule compliance | {rule validation} | {all rules pass on migrated data} |
+| Calculation accuracy | {formula verification} | {results match within tolerance} |
+
+## Rollback Plan
+{How to roll back if migration fails — backup strategy, point-in-time recovery}
+
+## Downtime Estimate
+{How long the database will be unavailable during migration, if at all}
+```
+
+---
+
+## Step 6: Sprint Breakdown
+
+Turn phases into actionable sprints. Each sprint should be 1-2 weeks with clear deliverables.
+
+### Output: `SPRINT_PLAN.md`
+
+```markdown
+# Sprint Plan
+
+## Sprint Conventions
+- **Duration**: {1 or 2 weeks}
+- **Team**: {size and roles}
+- **Definition of Done**: {what "done" means — tests passing, code reviewed, deployed to staging, etc.}
+
+---
+
+## Phase 0 Sprints
+
+### Sprint 0.1: Project Bootstrap
+**Goal**: Repo, CI/CD, and dev environment ready
+
+| Task | Assignee Role | Points | Details |
+|------|--------------|--------|---------|
+| Initialize {framework} project | Full-stack | {pts} | {specifics} |
+| Configure CI/CD pipeline | DevOps | {pts} | {specifics} |
+| Set up database | Backend | {pts} | {specifics} |
+| Configure linting, formatting, testing | Full-stack | {pts} | {specifics} |
+
+**Sprint Capacity**: {total points}
+**Risk**: {any sprint-specific risk}
+
+### Sprint 0.2: Auth & Core Infrastructure
+**Goal**: Authentication working, shared utilities built
+
+| Task | Assignee Role | Points | Details |
+|------|--------------|--------|---------|
+
+---
+
+## Phase 1 Sprints
+
+### Sprint 1.1: {Module Name} — Data Layer & API
+**Goal**: {module} backend complete with all endpoints and business rules
+
+| Task | Assignee Role | Points | Details |
+|------|--------------|--------|---------|
+| Create {entity} models | Backend | {pts} | Fields: {from DATA_MODELS.md} |
+| Implement {endpoint} | Backend | {pts} | Rules: {rule IDs from BUSINESS_RULES.md} |
+| Write tests for {rules} | Backend | {pts} | Cover: {specific edge cases} |
+
+### Sprint 1.2: {Module Name} — Frontend
+**Goal**: {module} UI complete and connected to API
+
+| Task | Assignee Role | Points | Details |
+|------|--------------|--------|---------|
+
+{Continue for all sprints across all phases}
+
+---
+
+## Sprint Summary
+| Sprint | Phase | Goal | Points | Modules Touched |
+|--------|-------|------|--------|----------------|
+| 0.1 | 0 | Bootstrap | {pts} | Infrastructure |
+| 0.2 | 0 | Auth & Core | {pts} | Auth, Shared |
+| 1.1 | 1 | {module} Backend | {pts} | {module} |
+| ... | ... | ... | ... | ... |
+```
+
+---
+
+## Step 7: Testing Strategy
+
+### Output: `TESTING_STRATEGY.md`
+
+```markdown
+# Testing Strategy
+
+## Approach
+{How testing fits into the redevelopment — what gets tested when, by whom}
+
+## Test Categories
+
+### Unit Tests
+- **Scope**: Every business rule from BUSINESS_RULES.md gets a unit test
+- **Coverage target**: {percentage}
+- **Key areas**: {list the modules with most complex logic}
+
+### Integration Tests
+- **Scope**: API endpoints, database queries, external service integrations
+- **Focus**: Every endpoint in API_REGISTRY.md tested with happy path + error cases
+
+### End-to-End Tests
+- **Scope**: Critical user workflows
+- **Workflows to cover**:
+  {List key workflows extracted from the intelligence package}
+
+### Regression Tests
+- **Purpose**: Verify new system matches legacy behavior
+- **Method**: Run same inputs through both systems, compare outputs
+- **Critical calculations**: {list formulas from BUSINESS_RULES.md that must match exactly}
+
+### Data Migration Tests
+- **Pre-migration**: Validate source data integrity
+- **Post-migration**: Verify all data migrated correctly (see DATA_MIGRATION.md verification)
+
+## Business Rule Test Matrix
+| Rule ID | Rule Name | Test Type | Priority |
+|---------|-----------|-----------|----------|
+| {id} | {name} | Unit | {high/medium/low} |
+
+{Map every extracted business rule to its test}
+```
+
+---
+
+## Step 8: Risk Register
+
+### Output: `RISK_REGISTER.md`
+
+```markdown
+# Risk Register
+
+| ID | Risk | Likelihood | Impact | Mitigation | Owner | Status |
+|----|------|-----------|--------|------------|-------|--------|
+| R1 | Undocumented business rules discovered mid-build | High | High | Intelligence package reduces this but can't eliminate it. Budget 15% buffer. Run legacy app in parallel for edge case discovery. | Tech Lead | Open |
+| R2 | Data migration corrupts production data | Medium | Critical | Dry-run migrations on staging copy. Checksums on every table. Rollback plan tested. | DBA | Open |
+| R3 | External API integrations behave differently than documented | Medium | High | Test each integration early in Phase 0. Contact external providers. | Backend Lead | Open |
+| R4 | Team underestimates effort on {complex module} | High | Medium | Front-load complex modules. Spike tickets for unknowns. | PM | Open |
+| R5 | Legacy system changes during migration (strangler fig) | Medium | Medium | Feature freeze on legacy modules being migrated. Sync protocol with stakeholders. | PM | Open |
+
+{Add project-specific risks based on what the intelligence package revealed —
+anti-patterns from RISK_REPORT.md, untested logic, security concerns, etc.}
+```
+
+---
+
+## Step 9: Assemble the Redevelopment Plan
+
+Combine all outputs into a single `REDEVELOPMENT_PLAN.md` executive summary, then deliver the full package.
+
+### Output: `REDEVELOPMENT_PLAN.md` (Executive Summary)
+
+```markdown
+# Redevelopment Plan: {Project Name}
+## {Legacy Stack} → {Target Stack}
+
+### Executive Summary
+{2-3 paragraphs: what the legacy app does, why it's being rewritten, what the plan is,
+how long it will take, key risks}
+
+### Key Numbers
+| Metric | Value |
+|--------|-------|
+| Legacy modules | {count} |
+| Business rules to preserve | {count} |
+| API endpoints to rebuild | {count} |
+| Data entities to migrate | {count} |
+| Estimated total effort | {developer-weeks} |
+| Estimated timeline | {weeks/months} |
+| Phases | {count} |
+| Sprints | {count} |
+
+### Migration Strategy
+{Summary — see MIGRATION_STRATEGY.md for details}
+
+### Architecture
+{Summary — see TARGET_ARCHITECTURE.md for details}
+
+### Phase Overview
+| Phase | Duration | Deliverable |
+|-------|----------|-------------|
+
+### Top Risks
+| Risk | Mitigation |
+|------|------------|
+
+### Detailed Plans
+- MIGRATION_STRATEGY.md
+- TARGET_ARCHITECTURE.md
+- EFFORT_ESTIMATION.md
+- PHASE_PLAN.md
+- DATA_MIGRATION.md
+- SPRINT_PLAN.md
+- TESTING_STRATEGY.md
+- RISK_REGISTER.md
+```
+
+### Final Output Folder Structure:
+
+```
+{project-name}-redevelopment-plan/
+├── REDEVELOPMENT_PLAN.md          ← Executive summary
+├── MIGRATION_STRATEGY.md
+├── TARGET_ARCHITECTURE.md
+├── EFFORT_ESTIMATION.md
+├── PHASE_PLAN.md
+├── DATA_MIGRATION.md
+├── SPRINT_PLAN.md
+├── TESTING_STRATEGY.md
+├── RISK_REGISTER.md
+└── diagrams/
+    ├── target-architecture.mermaid
+    ├── migration-sequence.mermaid
+    ├── phase-dependency.mermaid
+    └── data-migration-flow.mermaid
+```
+
+---
+
+## Quality Gate
+
+Before delivering, verify:
+
+- [ ] **Every business rule** from BUSINESS_RULES.md is accounted for in at least one sprint task
+- [ ] **Every API endpoint** from API_REGISTRY.md appears in the module mapping and sprint plan
+- [ ] **Every data entity** from DATA_MODELS.md has a migration plan
+- [ ] **Every external integration** from DEPENDENCIES.md has been planned for
+- [ ] **Phase ordering** respects the dependency chain from REPRODUCTION_GUIDE.md
+- [ ] **Effort estimates** are evidence-based (backed by rule counts, endpoint counts, not vibes)
+- [ ] **Risks** from RISK_REPORT.md are addressed in the risk register
+- [ ] **Sprint tasks** are specific enough to start working on immediately
+- [ ] **Testing strategy** covers every extracted business rule
+
+If any item fails, go back and fill the gap.
+
+---
+
+## Handling Incomplete Intelligence
+
+If the intelligence package is missing files or has gaps:
+
+1. Note which files are missing and what impact this has on planning confidence
+2. Reduce estimation confidence accordingly and add larger risk buffers
+3. Recommend running `codebase-legacy-intelligence` on the missing modules before finalizing the plan
+4. Mark affected sprint tasks as "needs spike" — investigation tasks to fill the knowledge gaps