| 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:
- All detected layers have been analyzed
- Verification pass has completed
- 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:
- Copy tables from layer docs - The reader can follow the reference link
- Duplicate code examples - Layer docs are the source of truth
- List every endpoint/table/entity - That's what layer docs are for
- Include implementation details - Focus on strategic decisions
- Repeat WHAT to build - Only discuss HOW to approach it
ALWAYS do these:
- Reference layer docs with links - Point to the detail, don't copy it
- Answer strategic questions - Database re-use? Test re-use? Frontend retention?
- Focus on phasing decisions - What order? What can be retained?
- Define validation approach - How to prove equivalence?
- Make recommendations - Give specific advice, not just options
Refresh Mode
If rebuild plan exists:
- Read existing plan
- Compare to new analysis
- Add
## Changes Since Last Plan section
- Update recommendations if layer findings changed
- Validate architecture.md still accurate
After Completion
Announce:
Rebuild strategy complete. See:
docs/unwind/REBUILD-PLAN.md - Strategic rebuild approach with re-use decisionsdocs/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.
