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

```markdown
# [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.