synthesizing-findings

name	synthesizing-findings
description	Use after layer analysis is complete to validate architecture documentation and generate a strategic rebuild plan focused on re-use decisions
allowed-tools	["Read","Grep","Glob","Bash(mkdir:*, ls:*)","Write(docs/unwind/**)","Edit(docs/unwind/**)"]

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 | Contract Type | Must Preserve |
|-------------|---------------|---------------|
| [Name] | [webhook/API/etc] | [Yes/No + reason] |


| Job | Frequency | Rebuild Approach |
|-----|-----------|------------------|
| [Name] | [cron] | [retain/adapt/rebuild] |

---






 [Components that can be kept as-is]


 [Components needing wrappers/bridges]


 [Components requiring full rebuild]

 [layers/xxx/index.md]


 [ ] [Specific check]
 [ ] [Specific check]



[Same structure]



[Same structure]



[Same structure]




 [How to run old and new side-by-side]
 [Traffic splitting approach]
 [Rollback triggers]

---





 [How to prove rebuilt system matches original]


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



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

---





| Layer | Reference | Readiness |
|-------|-----------|-----------|
| Database | []() | X/10 |
| Domain Model | []() | X/10 |
| Service Layer | []() | X/10 |
| API | []() | X/10 |
| Messaging | []() | X/10 |
| Frontend | []() | X/10 |
| Unit Tests | []() | X/10 |
| Integration Tests | []() | 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.