Synthesizing Findings → Rebuild Strategy

Overview

Transform layer analysis into a strategic rebuild plan that answers HOW to rebuild, not WHAT to rebuild.

Key Principle: Layer docs are the source of truth for what exists. The rebuild plan focuses on strategic decisions about re-use, phasing, and approach.

Requires: docs/unwind/layers/*/index.md from layer specialists + verification reports Produces:

• docs/unwind/REBUILD-PLAN.md - Strategic rebuild approach with re-use decisions
• Updated docs/unwind/architecture.md if corrections needed after detailed analysis

Does NOT produce:

• CODEBASE.md - Removed; architecture.md serves this purpose

Prerequisites

Before using this skill:

1. All detected layers have been analyzed
2. Verification pass has completed
3. Layer folders exist in docs/unwind/layers/ with index.md + section files

The Process

Step 1: Inventory Layer Documentation

Read all docs from docs/unwind/layers/:

• For each layer folder, read index.md and key section files
• Note item counts, readiness scores, and gaps identified
• Do NOT extract or copy content - just understand what exists

Step 2: Validate architecture.md

Compare initial architecture discovery against detailed layer findings:

• Are layer boundaries still accurate?
• Were any layers discovered/removed during analysis?
• Are cross-cutting concerns correctly identified?
• Update architecture.md if corrections are needed

Step 3: Assess Strategic Re-use Options

For each key area, determine what can be retained vs rebuilt:

Database:

• Can the rebuilt system connect to the live database?
• Is running alongside the original system feasible?
• Would a sync mechanism (change events, dual writes) be needed?

Tests:

• Are tests sufficiently decoupled from implementation details?
• Can existing tests validate the rebuilt system?
• What adapters would be needed for tech stack changes?

Frontend:

• Is the UI acceptable for initial phases?
• Can we replace only the backend initially?
• What API contract must be preserved exactly?

Integrations:

• Which external integrations are critical?
• What webhook contracts must be maintained?
• What scheduled jobs must continue?

Step 4: Determine Phasing Strategy

Based on re-use assessment, define phases:

• What can be retained as-is?
• What needs adapters/wrappers?
• What must be rebuilt from scratch?
• What's the dependency order?

Step 5: Define Validation Approach

Determine how to verify the rebuilt system matches the original:

• What test vectors exist?
• How can parallel running work?
• What metrics prove equivalence?

Step 6: Generate REBUILD-PLAN.md

Write strategic rebuild plan to docs/unwind/REBUILD-PLAN.md.

CRITICAL: Never copy content from layer docs. Only reference them.

Output Format: REBUILD-PLAN.md

# [Project Name] - Rebuild Strategy

> Generated by Unwind on [timestamp]

## Executive Summary

**Original Stack:** [brief tech summary]
**Overall Readiness:** [X/10]
**Recommended Approach:** [e.g., "Rebuild backend, retain frontend and database"]

---

## Strategic Decisions

### Database Strategy

**Question:** Can we connect to the live database during rebuild?

**Assessment:**
- [Findings from database layer analysis]
- [Multi-tenancy implications]
- [Schema compatibility considerations]

**Recommendation:** [Specific recommendation with rationale]

**Options if live DB not feasible:**
- [ ] Snapshot and restore to dev environment
- [ ] Build sync mechanism (change events)
- [ ] Dual-write during transition

### Test Re-usability

**Question:** Can we run existing tests against the rebuilt system?

**Assessment:**
- [Test coupling analysis from test layer docs]
- [Framework dependencies]
- [Tech-specific vs behavior-focused tests]

**Recommendation:** [Specific recommendation]

**Adapters needed:**
- [ ] [List any tech-specific adaptations]

### Frontend Retention

**Question:** Can we retain the frontend and replace only the backend?

**Assessment:**
- [Frontend coupling analysis]
- [API contract rigidity]
- [State management implications]

**Recommendation:** [Specific recommendation]

**API Contract:**
- Preserve exactly: [list critical endpoints/contracts]
- Can evolve: [list flexible areas]

### Integration Preservation

**External Services:**
| Integration | Contract Type | Must Preserve |
|-------------|---------------|---------------|
| [Name] | [webhook/API/etc] | [Yes/No + reason] |

**Scheduled Jobs:**
| Job | Frequency | Rebuild Approach |
|-----|-----------|------------------|
| [Name] | [cron] | [retain/adapt/rebuild] |

---

## Phasing Strategy

### Phase 1: [Foundation]

**Retain:**
- [Components that can be kept as-is]

**Adapt:**
- [Components needing wrappers/bridges]

**Rebuild:**
- [Components requiring full rebuild]

**Reference:** [layers/xxx/index.md]

**Validation:**
- [ ] [Specific check]
- [ ] [Specific check]

### Phase 2: [Core Logic]

[Same structure]

### Phase 3: [Interfaces]

[Same structure]

### Phase 4: [Frontend] (if rebuilding)

[Same structure]

### Phase 5: [Integration]

**Parallel Running Strategy:**
- [How to run old and new side-by-side]
- [Traffic splitting approach]
- [Rollback triggers]

---

## Validation Strategy

### Equivalence Testing

**Approach:** [How to prove rebuilt system matches original]

**Test Vectors:**
- [ ] Existing integration tests pass
- [ ] Calculation outputs match (specific test cases)
- [ ] API responses identical for sample requests

### Go-Live Checklist

- [ ] All phase validations complete
- [ ] Parallel running successful for [duration]
- [ ] Rollback tested
- [ ] Monitoring in place

---

## Layer Documentation References

> **Note:** These documents contain the detailed specifications. This plan focuses on strategic decisions only.

| Layer | Reference | Readiness |
|-------|-----------|-----------|
| Database | [layers/database/index.md](layers/database/index.md) | X/10 |
| Domain Model | [layers/domain-model/index.md](layers/domain-model/index.md) | X/10 |
| Service Layer | [layers/service-layer/index.md](layers/service-layer/index.md) | X/10 |
| API | [layers/api/index.md](layers/api/index.md) | X/10 |
| Messaging | [layers/messaging/index.md](layers/messaging/index.md) | X/10 |
| Frontend | [layers/frontend/index.md](layers/frontend/index.md) | X/10 |
| Unit Tests | [layers/unit-tests/index.md](layers/unit-tests/index.md) | X/10 |
| Integration Tests | [layers/integration-tests/index.md](layers/integration-tests/index.md) | X/10 |

Anti-Patterns

NEVER do these:

1. Copy tables from layer docs - The reader can follow the reference link
2. Duplicate code examples - Layer docs are the source of truth
3. List every endpoint/table/entity - That's what layer docs are for
4. Include implementation details - Focus on strategic decisions
5. Repeat WHAT to build - Only discuss HOW to approach it

ALWAYS do these:

1. Reference layer docs with links - Point to the detail, don't copy it
2. Answer strategic questions - Database re-use? Test re-use? Frontend retention?
3. Focus on phasing decisions - What order? What can be retained?
4. Define validation approach - How to prove equivalence?
5. Make recommendations - Give specific advice, not just options

Refresh Mode

If rebuild plan exists:

1. Read existing plan
2. Compare to new analysis
3. Add ## Changes Since Last Plan section
4. Update recommendations if layer findings changed
5. Validate architecture.md still accurate

After Completion

Announce:

Rebuild strategy complete. See:

• docs/unwind/REBUILD-PLAN.md - Strategic rebuild approach with re-use decisions
• docs/unwind/architecture.md - Validated architecture overview

The layer documentation contains the detailed specifications. The rebuild plan focuses on HOW to approach the rebuild, not WHAT to build.