Use Case #9: Phoenix Rebuild Pattern

Sometimes code is too broken to fix. Every change creates two new bugs. The architecture fights you. Technical debt has compounded into technical bankruptcy.

The GEOViz project hit that point.

The Situation

69 source files. 3 different state management approaches. API calls scattered everywhere. No consistent error handling. Tests? What tests?

The original vision was good. The documentation described a beautiful app. The code... did not match.

The Phoenix Prompt

"/phoenix the geoviz project. The repo and codebase suck pretty bad. Nonfunctional. Read through the documentation and plans because they were great. Make sure you understand the original intent then rebuild it correctly."

What Claude Did

Phase 1: Intent Extraction - Read all documentation: PRD, architecture diagrams, API specifications, user flow documents, component specifications. Built a mental model of what the app was supposed to be, ignoring what the code actually was.

Phase 2: Pattern Identification - From the docs, identified core data models, key user flows, integration points, and performance requirements.

Phase 3: Architecture Design - Designed a new architecture: single state management (Zustand), API layer abstraction, consistent error boundaries, type-safe from the start.

Phase 4: Implementation - Built the app fresh: new file structure, new components, new services, new tests. Reused: zero lines of original code.

Phase 5: Feature Parity Check - Compared the new build against documented requirements. Map visualization: broken → working. Data filtering: partial → complete. Export: missing → implemented. Performance: 4s load → 800ms load.

Why This Works

Documentation as source of truth. Bad code can corrupt understanding. Good docs preserve intent.

Fresh architecture. No inherited technical debt. No "well this was here so we kept it."

Verification against spec. The docs become acceptance criteria.

When to Phoenix

More than 50% of changes cause regressions. No one understands the full codebase. Documentation and code have diverged significantly. Adding features takes longer than the feature is worth.

Try It Yourself

Copy this to phoenix your own broken project:

I need to rebuild this project from its documentation (the code is too broken to salvage).

**Assessment:**
1. Where is the project? (repo path)
2. Where is the documentation? (docs folder / separate files / "find it")
3. What should the rebuilt version use? (same stack / updated stack / let me recommend)

**Approach:**
4. Should I preserve any code? (specific files/modules / no, rebuild everything)
5. What's the priority? (feature parity / performance / maintainability)

I will:
- Read all documentation to understand original intent
- Identify core requirements and data models
- Design a clean architecture
- Rebuild from scratch with modern patterns
- Verify against documented requirements
- Document what changed and why

Point me to the project and docs.

GEOViz was rebuilt in January 2026. Four months of bad code, replaced by one day of good code.