# Clean Slate Refactoring Plan

**Date:** 2026-05-18
**Source:** `docs/blueprints/AUDIT_REPORT.md`
**Master:** `UE5_Modular_Game_Framework.md`
**Goal:** Every Master-defined system has exactly 1 blueprint spec file with matching name. No bundled files. Consistent directory structure.

---

## 1. Problem Statement

The current `docs/blueprints/` tree has 83 files covering ~131 Master systems via bundling, renaming, and relocation. This makes blueprint authoring ambiguous: an implementer cannot find a Master system by its name because the file is renamed, bundled inside another file, or in the wrong directory. Clean Slate makes the mapping 1:1.

---

## 2. Proposed Solution

```mermaid
flowchart TD
    A[AUDIT_REPORT.md] --> B[Step 1: Rename 18 files to match Master]
    B --> C[Step 2: Split 2 bundled files into 12 individual files]
    C --> D[Step 3: Create 12 new Data Asset spec files in 12-data/]
    D --> E[Step 4: Create 30 new runtime system spec files in existing directories]
    E --> F[Step 5: Reorganize 11-polish/ into 3 sub-directories]
    F --> G[Step 6: Remove obsolete bundled umbrella files]
    G --> H[Step 7: Renumber all files sequentially across all directories]
    H --> I[Final: ~155 files, 1:1 master-to-file mapping]
```

---

## 3. Target Directory Structure (Final State)

```
docs/blueprints/
├── TEMPLATE.md
├── AUDIT_REPORT.md
├── 01-core/            (12 files)  — GameInstance, GameMode, GameState, Subsystems, Interfaces, FL, DataAssets
├── 02-player/          (9 files)   — All BPC_ player components + contextual traversal
├── 03-interaction/     (11 files)  — Interaction detection/execution, doors, puzzles, hiding spots, physics
├── 04-inventory/       (12 files)  — Inventory, equipment, items, combine, documents, journal, collectibles
├── 05-saveload/        (9 files)   — SaveManager, Persistable, Checkpoint, DeathOrchestrator, 4 death sub-systems
├── 06-ui/              (13 files)  — HUD, menus (1 per widget), notifications, screen effects, menu flow
├── 07-narrative/       (11 files)  — Narrative state, objectives, dialogue, choices, cutscenes, endings, lore
├── 08-weapons/         (12 files)  — Weapons, melee, firearms, ammo, damage, recoil, reload, shield, reactions
├── 09-ai/              (9 files)   — AI controller, perception, behavior trees, enemies, patrol, alert, state machine
├── 10-adaptive/        (9 files)   — Atmosphere, lighting, audio, VFX, fear, pacing, procedural encounters
├── 11-meta/            (6 files)   — Achievements, stats tracker, ending tracker, meta progression, run summary
├── 12-settings/        (5 files)   — Settings system, accessibility, haptics, platform abstraction, settings UI
├── 13-polish/          (10 files)  — Tutorial, loading, credits, splash, FPS, cheats, debug, analytics, error handler
└── 14-data-assets/     (13 files)  — 1 Data Asset Architecture overview + 12 individual DA_ specs
```

**Total files: ~155 (including TEMPLATE.md and AUDIT_REPORT.md)**

---

## 4. Operation Details

### 4.1 RENAME Operations (18 files)

Each rename changes the filename to match the Master document system name exactly.

| Current File | Directory | New Name | Master Ref | Reason |
|-------------|-----------|----------|------------|--------|
| `22_BPC_InventoryComponent.md` | 04-inventory | `BPC_InventorySystem.md` | Sec 4.1 | Master name |
| `25_BPC_EquipmentSystem.md` | 04-inventory | `BPC_EquipmentSlotSystem.md` | Sec 4.2 | Master name |
| `50_BP_RangedWeapon.md` | 08-weapons | `BPC_FirearmSystem.md` | Sec 5.2 | Wrong prefix + Master name |
| `51_BP_MeleeWeapon.md` | 08-weapons | `BPC_MeleeSystem.md` | Sec 5.1 | Wrong prefix + Master name |
| `53_BPC_DamageHandlerComponent.md` | 08-weapons | `BPC_DamageReceptionSystem.md` | Sec 5.6 | Master name |
| `33_WBP_HUD.md` | 06-ui | `WBP_HUDController.md` | Sec 6.1 | Master name |
| `35_WBP_InteractionUI.md` | 06-ui | `WBP_InteractionPromptDisplay.md` | Sec 6.3 | Master name |
| `34_WBP_InventoryUI.md` | 06-ui | `WBP_InventoryMenu.md` | Sec 6.4 | Master name |
| `45_BPC_EndingAccumulatorSystem.md` | 07-narrative | `BPC_EndingAccumulator.md` | Sec 7.8 | Drop System suffix |
| `47_BPC_NarrativeTriggerVolume.md` | 07-narrative | `BP_NarrativeTriggerVolume.md` | Sec 7.10 | Component→Actor |
| `55_BPC_AIControllerBase.md` | 09-ai | `AI_BaseAgentController.md` | Sec 10.1 | Master type prefix |
| `56_BPC_PerceptionComponent.md` | 09-ai | `BPC_AIPerceptionSystem.md` | Sec 10.3 | Master name |
| `64_BPC_AtmosphereController.md` | 10-adaptive | `BPC_AtmosphereStateController.md` | Sec 9.4 | Master name |
| `65_BPC_LightingManager.md` | 10-adaptive | `BPC_LightEventController.md` | Sec 9.6 | Master name |
| `66_BPC_AudioManager.md` | 10-adaptive | `BPC_AudioAtmosphereController.md` | Sec 9.7 | Master name |
| `20_BPC_InteractableDoorComponent.md` | 03-interaction | `BP_DoorActor.md` | Sec 3.5 | Master type + name |
| `30_BPC_CheckpointSystem.md` | 05-saveload | `BP_Checkpoint.md` | Sec 8.1 | Verify master name |
| `28_SS_SaveManager.md` | 05-saveload | Keep as-is | Sec 1.2 | Master uses SS_SaveSystem; file content is the save manager. Decision: keep SS_SaveManager as it accurately describes the subsystem. |

**Note on file 28:** Master Section 1 calls it `SS_SaveSystem` but the file is named `SS_SaveManager` and contains full save management logic. The Master Section 8 may use `SS_SaveManager`. For Clean Slate consistency, the file stays as `SS_SaveManager` since that's what the detailed system definition calls it.

### 4.2 SPLIT Operations (2 bundled files → 12 individual files)

#### 4.2.1 Split `31_BPC_DeathHandlingSystem.md` → 5 files

The existing file (311 lines) contains the orchestrator component plus 4 sub-systems each with purpose, variables, functions, and event dispatchers. Each sub-system becomes a standalone file. The orchestrator keeps the parent-level enums, structs, core component variables, core functions, the flow diagram, and the communication matrix.

| # | New File | Source Lines | System Name |
|---|----------|-------------|-------------|
| 1 | `BPC_DeathHandlingSystem.md` | 1-64, 206-311 | Orchestrator (enums, structs, core vars, core fns, flow, matrix) |
| 2 | `BPC_AltDeathSpaceSystem.md` | 65-99 | Alt death space management |
| 3 | `BPC_PersistentCorpseSystem.md` | 102-132 | Corpse spawning and persistence |
| 4 | `BPC_PlayerRespawnSystem.md` | 136-167 | Respawn mechanics |
| 5 | `BPC_RunHistoryTracker.md` | 171-203 | Run-level death tracking |

**Mapping:** Master Section 8 lists `BPC_AltDeathSpaceSystem`, `BPC_PlayerRespawnSystem`, `BPC_RunHistoryTracker` as separate systems (8.5–8.7). The split matches the Master's structure.

#### 4.2.2 Split `36_WBP_MenuWidgets.md` → 7 files

The existing file (353 lines) bundles 6 widgets under one umbrella. Each widget has its own purpose, variables, functions, and in one case an enum. Split each into a standalone file.

| # | New File | Source Lines | Widget Name |
|---|----------|-------------|-------------|
| 1 | `WBP_MainMenu.md` | 15-48 | Title screen with New/Continue/Load/Settings/Credits/Quit |
| 2 | `WBP_PauseMenu.md` | 51-94 | In-game pause overlay |
| 3 | `WBP_SettingsMenu.md` | 99-188 | Full settings screen with 5 tabs |
| 4 | `WBP_NotificationToast.md` | 191-230 | Non-blocking toast notification |
| 5 | `WBP_ScreenEffectController.md` | 233-261 | Damage vignettes, jump scare flash, stress distortion |
| 6 | `WBP_MenuFlowController.md` | 264-353 | Menu state transitions, fades, level loading |
| 7 | *(Extra)* `WBP_ObjectiveDisplay.md` | — | Not in bundled file; master lists it as 6.6 |

**Mapping:** Master Section 6 lists all 6 widgets plus `WBP_ObjectiveDisplay` (Sec 6.6), `WBP_SubtitleDisplay` (Sec 6.7), `WBP_JournalDocumentViewer` (Sec 6.5), and `WBP_DiegeticHUDFrame` (Sec 6.2). The existing `37_WBP_AccessibilityUI.md` already covers subtitles. Two widgets remain missing (`WBP_JournalDocumentViewer`, `WBP_DiegeticHUDFrame` — addressed in section 4.4).

**Original umbrella file `36_WBP_MenuWidgets.md` is DELETED after splits.**

### 4.3 CREATE Operations — 12 Data Asset Specs (new `14-data-assets/` directory)

Master Section 13 defines 20 Data Asset types. 8 are already covered (`07_DA_ItemData.md`, `48_DA_NarrativeDataAssets.md` covers 5, `49_BP_WeaponBase.md` covers `DA_WeaponData`, `74_BPC_AchievementManager.md` implicitly covers `DA_AchievementData`). 12 have no spec.

Create these 13 files in a new `docs/blueprints/14-data-assets/` directory:

| # | File | Master Ref | Purpose |
|---|------|------------|---------|
| 1 | `DA_DataAssetArchitecture.md` | Sec 13 overview | All 20 DA types, naming conventions, dependency rules, build order |
| 2 | `DA_InteractionData.md` | Sec 13 | Interaction prompt types, requirements, target filters |
| 3 | `DA_ObjectiveData.md` | Sec 13 | Objective definitions, states, rewards |
| 4 | `DA_EncounterData.md` | Sec 13 | Enemy encounter configurations |
| 5 | `DA_AtmosphereProfile.md` | Sec 13 | Lighting, audio, fog, post-process presets |
| 6 | `DA_ScareEvent.md` | Sec 13 | Scare trigger definitions, jump scares, ambient horror |
| 7 | `DA_RoomMutation.md` | Sec 13 | Environmental mutation content, memory drift |
| 8 | `DA_BehaviourVariant.md` | Sec 13 | AI behavior variant stats, aggression, patrol patterns |
| 9 | `DA_HapticProfile.md` | Sec 13 | DualSense/DualShock haptic patterns |
| 10 | `DA_AdaptationRule.md` | Sec 13 | Adaptive director rule sets |
| 11 | `DA_EquipmentConfig.md` | Sec 13 | Equipment slot configurations |
| 12 | `DA_PuzzleData.md` | Sec 13 | Puzzle solution definitions, input/output mappings |
| 13 | `DA_RareEvent.md` | Sec 13 | Rare world event definitions |

**Each Data Asset spec must include:** Parent Class (`UDataAsset`), Gameplay Tags namespace, struct definition for rows, example data rows, validation rules, and which systems consume it.

### 4.4 CREATE Operations — 30 Runtime System Specs (in existing directories)

#### 03-interaction/ (add 4 files)
| # | File | Master Ref | Purpose |
|---|------|------------|---------|
| 1 | `BPC_PhysicsDragSystem.md` | Sec 3.4 | Physics grab, drag, throw |
| 2 | `BPC_ContextualTraversalSystem.md` | Sec 3.8 | Vault, climb, ledge grab |
| 3 | `BP_PuzzleDeviceActor.md` | Sec 3.9 | Generic puzzle with input/output |
| 4 | `BPC_UsableWorldObjectSystem.md` | Sec 3.10 | Light switches, levers, simple on/off objects |

#### 04-inventory/ (add 7 files)
| # | File | Master Ref | Purpose |
|---|------|------------|---------|
| 1 | `BPC_ActiveItemSystem.md` | Sec 4.3 | Active hand item, raise/lower animations |
| 2 | `BPC_ItemCombineSystem.md` | Sec 4.5 | Item combination mechanic |
| 3 | `BPC_DocumentArchiveSystem.md` | Sec 4.6 | Document/note storage and reading |
| 4 | `BPC_JournalSystem.md` | Sec 4.7 | Player journal with entries |
| 5 | `BPC_CollectibleTracker.md` | Sec 4.8 | Collectible discovery tracking |
| 6 | `BPC_ConsumableSystem.md` | Sec 4.9 | Consumable item usage logic |
| 7 | `BPC_KeyItemSystem.md` | Sec 4.11 | Key item management and protection |

#### 05-saveload/ (add 1 file)
| # | File | Master Ref | Purpose |
|---|------|------------|---------|
| 1 | `BPC_PersistentWorldStateRecorder.md` | Sec 8.2 | World state recording for save (currently bundled in SS_SaveManager) |

#### 06-ui/ (add 3 files)
| # | File | Master Ref | Purpose |
|---|------|------------|---------|
| 1 | `WBP_DiegeticHUDFrame.md` | Sec 6.2 | Swappable diegetic HUD skin |
| 2 | `WBP_JournalDocumentViewer.md` | Sec 6.5 | Document and journal display widget |
| 3 | `WBP_ObjectiveDisplay.md` | Sec 6.6 | Objective overlay widget |

#### 08-weapons/ (add 5 files)
| # | File | Master Ref | Purpose |
|---|------|------------|---------|
| 1 | `BPC_RecoilSystem.md` | Sec 5.3 | Procedural recoil |
| 2 | `BPC_ReloadSystem.md` | Sec 5.4 | Weapon reload management |
| 3 | `BPC_ShieldDefenseSystem.md` | Sec 5.5 | Blocking and parrying |
| 4 | `BPC_HitReactionSystem.md` | Sec 5.7 | Hit reaction behaviour |
| 5 | `BPC_DeathCauseTracker.md` | Sec 5.8 | Death cause logging |

**Note:** `BPC_AmmoResourceSystem` (Sec 4.10) is handled by moving/renaming `52_BPC_AmmoComponent.md` from 08-weapons to 04-inventory.

#### 09-ai/ (add 3 files + relocate 1)
| # | File | Master Ref | Purpose |
|---|------|------------|---------|
| 1 | `BB_AgentBoard.md` | Sec 10.2 | Blackboard asset for AI agents |
| 2 | `BPC_AIMemorySystem.md` | Sec 10.4 | AI memory of player actions |
| 3 | `BPC_BehaviourVariantSelector.md` | Sec 10.5 | Behaviour variant selection |
| 4 | `BPC_EncounterDirector.md` | Sec 10.6 | Relocated from 10-adaptive (currently `70_BPC_ProceduralEncounter.md`) |

#### 10-adaptive/ (add 5 files)
| # | File | Master Ref | Purpose |
|---|------|------------|---------|
| 1 | `BPC_PlaystyleClassifier.md` | Sec 9.1 | Player playstyle analysis |
| 2 | `BPC_AdaptiveEnvironmentDirector.md` | Sec 9.2 | Master adaptive controller |
| 3 | `BPC_MemoryDriftSystem.md` | Sec 9.3 | Room mutation / environmental drift |
| 4 | `BPC_ScareEventSystem.md` | Sec 9.5 | Scare event scheduling and triggering |
| 5 | `BPC_PacingDirector.md` | Sec 9.8 | Tension and pacing control |
| 6 | `BPC_RareEventSystem.md` | Sec 9.9 | Rare world events |

#### New 11-meta/ directory (move 3 from 11-polish + add 3 new)
Existing files to move from 11-polish:
- `74_BPC_AchievementManager.md` → `SS_AchievementSystem.md`
- `75_BPC_StatsTracker.md` → `BPC_ProgressStatTracker.md`

New files:
| # | File | Master Ref | Purpose |
|---|------|------------|---------|
| 1 | `BPC_EndingCompletionTracker.md` | Sec 11.4 | Ending tracking across save files |
| 2 | `BPC_MetaProgressionSystem.md` | Sec 11.5 | NG+ unlock system |
| 3 | `BPC_RunSummarySystem.md` | Sec 11.6 | End-of-run summary generation |

#### New 12-settings/ directory (move 2 from 11-polish + add 2 new)
Existing files to move from 11-polish:
- `71_SS_SettingsManager.md` → `SS_SettingsSystem.md`
- `72_BPC_AccessibilitySettings.md`

New files:
| # | File | Master Ref | Purpose |
|---|------|------------|---------|
| 1 | `BPC_HapticsController.md` | Sec 12.2 | Haptic feedback (DualSense) |
| 2 | `BPC_PlatformServiceAbstraction.md` | Sec 12.3 | Platform API abstraction layer |

### 4.5 REORGANIZE Operations — 11-polish/ split into 3 directories

The current `11-polish/` directory has 13 files spanning 3 different Master sections plus extras. Split into:

**11-meta/** (6 files) — Achievement, progression, meta systems:
- `SS_AchievementSystem.md` (from `74_BPC_AchievementManager.md`)
- `DA_AchievementData.md` (extracted from achievement manager or optionally kept bundled)
- `BPC_ProgressStatTracker.md` (from `75_BPC_StatsTracker.md`)
- `BPC_EndingCompletionTracker.md` (new)
- `BPC_MetaProgressionSystem.md` (new)
- `BPC_RunSummarySystem.md` (new)

**12-settings/** (5 files) — Settings, accessibility, platform:
- `SS_SettingsSystem.md` (from `71_SS_SettingsManager.md`)
- `BPC_AccessibilitySettings.md` (from `72_BPC_AccessibilitySettings.md`)
- `BPC_HapticsController.md` (new)
- `BPC_PlatformServiceAbstraction.md` (new)
- `WBP_SettingsMenu.md` (from 06-ui after menu split — it's the settings widget)

**13-polish/** (10 files) — Remaining polish/extras:
- `BPC_TutorialSystem.md` (from `73_BPC_TutorialSystem.md`)
- `BPC_LoadingScreen.md` (from `76_BPC_LoadingScreen.md`)
- `WBP_CreditsScreen.md` (from `77_WBP_CreditsScreen.md`)
- `WBP_SplashScreen.md` (from `78_WBP_SplashScreen.md`)
- `BPC_FPSCounter.md` (from `79_BPC_FPSCounter.md`)
- `BPC_DevCheatManager.md` (from `80_BPC_DevCheatManager.md`)
- `WBP_DebugMenu.md` (from `81_WBP_DebugMenu.md`)
- `BPC_AnalyticsTracker.md` (from `82_BPC_AnalyticsTracker.md`)
- `BPC_ErrorHandler.md` (from `83_BPC_ErrorHandler.md`)
- `WBP_NotificationToast.md` (relocated from 06-ui after menu split — it's a global toast, not menu-specific)

### 4.6 RENUMBER Operations

After all renames, splits, creates, and reorganizations, assign sequential numbering starting from 01. Numbering is global across all directories (keeps the current convention).

**Numbering Priority Order:**
1. 01-core/ → 1–12
2. 02-player/ → 13–21
3. 03-interaction/ → 22–32
4. 04-inventory/ → 33–44
5. 05-saveload/ → 45–53
6. 06-ui/ → 54–66
7. 07-narrative/ → 67–77
8. 08-weapons/ → 78–89
9. 09-ai/ → 90–98
10. 10-adaptive/ → 99–107
11. 11-meta/ → 108–113
12. 12-settings/ → 114–118
13. 13-polish/ → 119–128
14. 14-data-assets/ → 129–141

**Total: ~141 numbered files + TEMPLATE.md + AUDIT_REPORT.md = ~143 total**

### 4.7 DELETE Operations

| File to Delete | Reason |
|---------------|--------|
| `06-ui/36_WBP_MenuWidgets.md` | Split into 7 individual widget files |
| `05-saveload/31_BPC_DeathHandlingSystem.md` (original) | Replaced by 5 split files |
| `03-interaction/17_BPC_PickupComponent.md` | Not in Master; functionality covered by InteractionExecutor + ItemPickup |
| `03-interaction/19_BPC_LeverPuzzleComponent.md` | Not in Master; covered by `BP_PuzzleDeviceActor` |
| `04-inventory/23_BPC_InventoryWeightSystem.md` | Not in Master; weight is a sub-feature of InventorySystem |
| `04-inventory/24_BPC_InventoryQuickSlot.md` | Not in Master; quick slots are sub-feature of ActiveItemSystem |
| `09-ai/57_BPC_BehaviorTreeManager.md` | Not in Master; covered by `BB_AgentBoard` + `BPC_BehaviourVariantSelector` |

---

## 5. File Count Summary

| Phase | Operation | Count |
|-------|-----------|-------|
| **Start** | Existing files (including TEMPLATE + AUDIT) | 85 |
| | Rename (in-place, no net change) | 18 |
| | Split 2 bundled → 12 individual (-2 +12) | +10 |
| | Create new runtime specs | +30 |
| | Create new Data Asset specs | +13 |
| | Reorganize (move across dirs, no net change) | 0 |
| | Delete extra/unmatched files | -7 |
| **End** | **Final file count** | **~141** |

---

## 6. Dependencies and Rules

### Content Creation Rules (for Execution Agent)
1. Every new file MUST follow [`TEMPLATE.md`](../blueprints/TEMPLATE.md) format
2. Parent Class, Dependencies, Purpose are mandatory sections
3. Variables must have Name, Type, Description columns
4. Functions must have Name, Inputs, Outputs, Description columns
5. Event Dispatchers must have Name, Parameters, "Fired When" columns
6. Every spec must include a Blueprint Flow Diagram (Mermaid)
7. Every spec must include a Communication Matrix
8. Every spec must include Reuse Notes

### Master Document Authority
- The Master document (`UE5_Modular_Game_Framework.md`) is the single source of truth for system names, types, and dependencies
- When in doubt about a variable or function name, consult the Master document section for that system
- If the Master document does not specify a detail, use the naming conventions defined in Section 13 of the Master

### Naming Conventions (from Master Section 13)
| Prefix | Asset Type |
|--------|-----------|
| `BP_` | Blueprint Actor |
| `BPC_` | Blueprint Actor Component |
| `WBP_` | Widget Blueprint |
| `I_` | Blueprint Interface |
| `DA_` | Data Asset |
| `E_` | Enumeration |
| `S_` | Structure |
| `GI_` | Game Instance |
| `GM_` | Game Mode |
| `GS_` | Game State |
| `SS_` | Subsystem |
| `FL_` | Function Library |
| `AI_` | AI Controller |
| `BB_` | Blackboard |
| `BTT_` | Behavior Tree Task |
| `BTS_` | Behavior Tree Service |
| `BTD_` | Behavior Tree Decorator |

---

## 7. Success Criteria

1. Every system in the Master document (Sections 1–13) has exactly 1 blueprint spec file
2. Every blueprint spec file name matches the Master system name exactly (including prefix)
3. No file bundles multiple Master-defined systems
4. Directory structure maps cleanly to Master sections
5. All markdown cross-references (`[link](file.md)`) are valid
6. All files follow TEMPLATE.md format
7. Sequential file numbering is contiguous from 01 to ~141
8. AUDIT_REPORT.md is updated to reflect final state (all ✅)
9. CONTEXT.md is updated with final directory structure and file count
10. `git status` shows clean, logical file operations (renames detected as renames, not delete+create)

---

*End of Clean Slate Plan*