UE5-Modular-Game-Framework/docs/checklists/clean-slate-refactor.md

# Clean Slate Refactoring — Implementation Checklist

**Source Plan:** [`docs/architecture/CLEAN_SLATE_PLAN.md`](../architecture/CLEAN_SLATE_PLAN.md)
**Master Document:** [`UE5_Modular_Game_Framework.md`](../../UE5_Modular_Game_Framework.md)
**Audit:** [`docs/blueprints/AUDIT_REPORT.md`](../../docs/blueprints/AUDIT_REPORT.md)
**Template:** [`docs/blueprints/TEMPLATE.md`](../../docs/blueprints/TEMPLATE.md)

---

## Phase 0 — Setup

- [ ] 0.1 Verify current `git status` is clean (commit any pending changes first)
- [ ] 0.2 Create branch `refactor/clean-slate` from `main`
- [ ] 0.3 Confirm all 83 blueprint files are readable and not corrupted

---

## Phase 1 — Rename 18 Files to Match Master Naming

Each task: delete old file, create new file at same location with corrected name, update internal header line.

### 03-interaction/
- [ ] 1.1 Rename `20_BPC_InteractableDoorComponent.md` → `BP_DoorActor.md`

### 04-inventory/
- [ ] 1.2 Rename `22_BPC_InventoryComponent.md` → `BPC_InventorySystem.md`
- [ ] 1.3 Rename `25_BPC_EquipmentSystem.md` → `BPC_EquipmentSlotSystem.md`

### 05-saveload/
- [ ] 1.4 Rename `30_BPC_CheckpointSystem.md` → `BP_Checkpoint.md` (if Master uses BP_ prefix; verify against Master line)

### 06-ui/
- [ ] 1.5 Rename `33_WBP_HUD.md` → `WBP_HUDController.md`
- [ ] 1.6 Rename `34_WBP_InventoryUI.md` → `WBP_InventoryMenu.md`
- [ ] 1.7 Rename `35_WBP_InteractionUI.md` → `WBP_InteractionPromptDisplay.md`

### 07-narrative/
- [ ] 1.8 Rename `45_BPC_EndingAccumulatorSystem.md` → `BPC_EndingAccumulator.md`
- [ ] 1.9 Rename `47_BPC_NarrativeTriggerVolume.md` → `BP_NarrativeTriggerVolume.md`

### 08-weapons/
- [ ] 1.10 Rename `50_BP_RangedWeapon.md` → `BPC_FirearmSystem.md`
- [ ] 1.11 Rename `51_BP_MeleeWeapon.md` → `BPC_MeleeSystem.md`
- [ ] 1.12 Rename `53_BPC_DamageHandlerComponent.md` → `BPC_DamageReceptionSystem.md`

### 09-ai/
- [ ] 1.13 Rename `55_BPC_AIControllerBase.md` → `AI_BaseAgentController.md`
- [ ] 1.14 Rename `56_BPC_PerceptionComponent.md` → `BPC_AIPerceptionSystem.md`

### 10-adaptive/
- [ ] 1.15 Rename `64_BPC_AtmosphereController.md` → `BPC_AtmosphereStateController.md`
- [ ] 1.16 Rename `65_BPC_LightingManager.md` → `BPC_LightEventController.md`
- [ ] 1.17 Rename `66_BPC_AudioManager.md` → `BPC_AudioAtmosphereController.md`

### Verify
- [ ] 1.18 Verify all 18 renamed files exist and old files are deleted

---

## Phase 2 — Split Two Bundled Files

### 2.1 Split DeathHandlingSystem (1 file → 5 files)

**Read source:** `05-saveload/31_BPC_DeathHandlingSystem.md` (311 lines)

- [ ] 2.1.1 Create `05-saveload/BPC_DeathHandlingSystem.md` — Core orchestrator content (lines 1-64 enums/structs + 206-311 core vars/fns/flow/matrix + header section)
- [ ] 2.1.2 Create `05-saveload/BPC_AltDeathSpaceSystem.md` — Alt death space sub-system (lines 65-99)
- [ ] 2.1.3 Create `05-saveload/BPC_PersistentCorpseSystem.md` — Corpse sub-system (lines 102-132)
- [ ] 2.1.4 Create `05-saveload/BPC_PlayerRespawnSystem.md` — Respawn sub-system (lines 136-167)
- [ ] 2.1.5 Create `05-saveload/BPC_RunHistoryTracker.md` — Run history sub-system (lines 171-203)

**Each split file must:**
- Include a `Depends On:` section referencing the orchestrator and relevant systems
- Include a `Purpose:` header describing its standalone role
- Follow TEMPLATE.md format with complete sections

- [ ] 2.1.6 Delete original `05-saveload/31_BPC_DeathHandlingSystem.md`
- [ ] 2.1.7 Verify all 5 new files are self-contained and valid

### 2.2 Split MenuWidgets (1 file → 7 files)

**Read source:** `06-ui/36_WBP_MenuWidgets.md` (353 lines)

- [ ] 2.2.1 Create `06-ui/WBP_MainMenu.md` — Main menu widget (lines 15-48)
- [ ] 2.2.2 Create `06-ui/WBP_PauseMenu.md` — Pause menu widget (lines 51-94)
- [ ] 2.2.3 Create `06-ui/WBP_SettingsMenu.md` — Settings menu widget (lines 99-188)
- [ ] 2.2.4 Create `06-ui/WBP_NotificationToast.md` — Toast notification widget (lines 191-230)
- [ ] 2.2.5 Create `06-ui/WBP_ScreenEffectController.md` — Screen effects widget (lines 233-261)
- [ ] 2.2.6 Create `06-ui/WBP_MenuFlowController.md` — Menu flow widget (lines 264-353)
- [ ] 2.2.7 Create `06-ui/WBP_ObjectiveDisplay.md` — New file (not in bundled source; Master Sec 6.6)

**Note for 2.2.7:** `WBP_ObjectiveDisplay` is listed in Master Section 6.6 but was NOT in the bundled `WBP_MenuWidgets.md`. Create from scratch using TEMPLATE.md. It displays current objectives as an overlay.

- [ ] 2.2.8 Delete original `06-ui/36_WBP_MenuWidgets.md`
- [ ] 2.2.9 Verify all 7 new files are self-contained and valid

---

## Phase 3 — Create 12 Data Asset Spec Files (new `14-data-assets/` directory)

All DA files should follow this structure:
```
# DA_<Name> — Data Asset
**Parent Class:** `UDataAsset`
**Dependencies:** (systems that consume this data)
**Purpose:** (what content this data asset defines)

## Variables / Structure
(complete row structure definition)

## Gameplay Tags
(tag namespace this DA operates in)

## Validation Rules
(editor-time validation logic)

## Example Data
(1-2 example rows)

## Consumed By
(systems that read this DA)

## Reuse Notes
```

- [ ] 3.0 Create directory `docs/blueprints/14-data-assets/`
- [ ] 3.1 Create `14-data-assets/DA_DataAssetArchitecture.md` — overview of all 20 DA types, naming conventions, dependency rules
- [ ] 3.2 Create `14-data-assets/DA_InteractionData.md`
- [ ] 3.3 Create `14-data-assets/DA_ObjectiveData.md`
- [ ] 3.4 Create `14-data-assets/DA_EncounterData.md`
- [ ] 3.5 Create `14-data-assets/DA_AtmosphereProfile.md`
- [ ] 3.6 Create `14-data-assets/DA_ScareEvent.md`
- [ ] 3.7 Create `14-data-assets/DA_RoomMutation.md`
- [ ] 3.8 Create `14-data-assets/DA_BehaviourVariant.md`
- [ ] 3.9 Create `14-data-assets/DA_HapticProfile.md`
- [ ] 3.10 Create `14-data-assets/DA_AdaptationRule.md`
- [ ] 3.11 Create `14-data-assets/DA_EquipmentConfig.md`
- [ ] 3.12 Create `14-data-assets/DA_PuzzleData.md`
- [ ] 3.13 Create `14-data-assets/DA_RareEvent.md`

---

## Phase 4 — Create 30 Runtime System Spec Files

### 03-interaction/ (4 files)
- [ ] 4.1 Create `03-interaction/BPC_PhysicsDragSystem.md`
- [ ] 4.2 Create `03-interaction/BPC_ContextualTraversalSystem.md`
- [ ] 4.3 Create `03-interaction/BP_PuzzleDeviceActor.md`
- [ ] 4.4 Create `03-interaction/BPC_UsableWorldObjectSystem.md`

### 04-inventory/ (7 files)
- [ ] 4.5 Create `04-inventory/BPC_ActiveItemSystem.md`
- [ ] 4.6 Create `04-inventory/BPC_ItemCombineSystem.md`
- [ ] 4.7 Create `04-inventory/BPC_DocumentArchiveSystem.md`
- [ ] 4.8 Create `04-inventory/BPC_JournalSystem.md`
- [ ] 4.9 Create `04-inventory/BPC_CollectibleTracker.md`
- [ ] 4.10 Create `04-inventory/BPC_ConsumableSystem.md`
- [ ] 4.11 Create `04-inventory/BPC_KeyItemSystem.md`

### 05-saveload/ (1 file)
- [ ] 4.12 Create `05-saveload/BPC_PersistentWorldStateRecorder.md`

### 06-ui/ (3 files)
- [ ] 4.13 Create `06-ui/WBP_DiegeticHUDFrame.md`
- [ ] 4.14 Create `06-ui/WBP_JournalDocumentViewer.md`
- [ ] 4.15 Create `06-ui/WBP_ObjectiveDisplay.md` (already created in Phase 2.2.7)

### 08-weapons/ (5 files)
- [ ] 4.16 Create `08-weapons/BPC_RecoilSystem.md`
- [ ] 4.17 Create `08-weapons/BPC_ReloadSystem.md`
- [ ] 4.18 Create `08-weapons/BPC_ShieldDefenseSystem.md`
- [ ] 4.19 Create `08-weapons/BPC_HitReactionSystem.md`
- [ ] 4.20 Create `08-weapons/BPC_DeathCauseTracker.md`

### 09-ai/ (3 files)
- [ ] 4.21 Create `09-ai/BB_AgentBoard.md`
- [ ] 4.22 Create `09-ai/BPC_AIMemorySystem.md`
- [ ] 4.23 Create `09-ai/BPC_BehaviourVariantSelector.md`

### 10-adaptive/ (6 files)
- [ ] 4.24 Create `10-adaptive/BPC_PlaystyleClassifier.md`
- [ ] 4.25 Create `10-adaptive/BPC_AdaptiveEnvironmentDirector.md`
- [ ] 4.26 Create `10-adaptive/BPC_MemoryDriftSystem.md`
- [ ] 4.27 Create `10-adaptive/BPC_ScareEventSystem.md`
- [ ] 4.28 Create `10-adaptive/BPC_PacingDirector.md`
- [ ] 4.29 Create `10-adaptive/BPC_RareEventSystem.md`

---

## Phase 5 — Reorganize 11-polish/ into 3 New Directories

### 5.1 Create new directories
- [ ] 5.1.1 Create `docs/blueprints/11-meta/`
- [ ] 5.1.2 Create `docs/blueprints/12-settings/`
- [ ] 5.1.3 Create `docs/blueprints/13-polish/`

### 5.2 Move files to 11-meta/ (3 files)
- [ ] 5.2.1 Move `11-polish/74_BPC_AchievementManager.md` → `11-meta/SS_AchievementSystem.md`
- [ ] 5.2.2 Move `11-polish/75_BPC_StatsTracker.md` → `11-meta/BPC_ProgressStatTracker.md`
- [ ] 5.2.3 Create `11-meta/BPC_EndingCompletionTracker.md` (new)
- [ ] 5.2.4 Create `11-meta/BPC_MetaProgressionSystem.md` (new)
- [ ] 5.2.5 Create `11-meta/BPC_RunSummarySystem.md` (new)

### 5.3 Move files to 12-settings/ (4 files)
- [ ] 5.3.1 Move `11-polish/71_SS_SettingsManager.md` → `12-settings/SS_SettingsSystem.md`
- [ ] 5.3.2 Move `11-polish/72_BPC_AccessibilitySettings.md` → `12-settings/BPC_AccessibilitySettings.md`
- [ ] 5.3.3 Create `12-settings/BPC_HapticsController.md` (new)
- [ ] 5.3.4 Create `12-settings/BPC_PlatformServiceAbstraction.md` (new)

### 5.4 Move remaining files to 13-polish/ (9 files)
- [ ] 5.4.1 Move `11-polish/73_BPC_TutorialSystem.md` → `13-polish/BPC_TutorialSystem.md`
- [ ] 5.4.2 Move `11-polish/76_BPC_LoadingScreen.md` → `13-polish/BPC_LoadingScreen.md`
- [ ] 5.4.3 Move `11-polish/77_WBP_CreditsScreen.md` → `13-polish/WBP_CreditsScreen.md`
- [ ] 5.4.4 Move `11-polish/78_WBP_SplashScreen.md` → `13-polish/WBP_SplashScreen.md`
- [ ] 5.4.5 Move `11-polish/79_BPC_FPSCounter.md` → `13-polish/BPC_FPSCounter.md`
- [ ] 5.4.6 Move `11-polish/80_BPC_DevCheatManager.md` → `13-polish/BPC_DevCheatManager.md`
- [ ] 5.4.7 Move `11-polish/81_WBP_DebugMenu.md` → `13-polish/WBP_DebugMenu.md`
- [ ] 5.4.8 Move `11-polish/82_BPC_AnalyticsTracker.md` → `13-polish/BPC_AnalyticsTracker.md`
- [ ] 5.4.9 Move `11-polish/83_BPC_ErrorHandler.md` → `13-polish/BPC_ErrorHandler.md`

### 5.5 Clean up
- [ ] 5.5.1 Delete empty `11-polish/` directory

---

## Phase 6 — Delete Extra/Unmatched Files (7 files)

These files define systems not present in the Master document or are replaced by split/new files:

- [ ] 6.1 Delete `03-interaction/17_BPC_PickupComponent.md` (covered by ItemPickup + InteractionExecutor)
- [ ] 6.2 Delete `03-interaction/19_BPC_LeverPuzzleComponent.md` (covered by BP_PuzzleDeviceActor)
- [ ] 6.3 Delete `04-inventory/23_BPC_InventoryWeightSystem.md` (sub-feature of InventorySystem)
- [ ] 6.4 Delete `04-inventory/24_BPC_InventoryQuickSlot.md` (sub-feature of ActiveItemSystem)
- [ ] 6.5 Delete `09-ai/57_BPC_BehaviorTreeManager.md` (covered by BB_AgentBoard + BehaviourVariantSelector)
- [ ] 6.6 Delete `10-adaptive/68_BP_DynamicEvent.md` (covered by BPC_RareEventSystem)
- [ ] 6.7 Delete `10-adaptive/67_BPC_VFXManager.md` (not in Master; VFX controlled by AtmosphereController)

---

## Phase 7 — Renumber All Files Sequentially

After all renames/splits/creates/moves/deletes, renumber every file prefixed with `XX_` (where XX is the existing number).

**New numbering order:**
1. 01-core/ → 01–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

**Renumbering rules:**
- Each file gets prefix `XX_` where XX is zero-padded to 2 digits
- The prefix matches the directory's slot in the numbering order
- Example: `01-core/01_GI_GameFramework.md` stays `01_`. `06-ui/` files get `54_` through `66_`.
- Internal cross-references in each file must be updated to new filenames

- [ ] 7.1 Renumber 01-core/ files (7 files → verify, may need expansion to 12)
- [ ] 7.2 Renumber 02-player/ files (9 files → 13–21)
- [ ] 7.3 Renumber 03-interaction/ files (11 files → 22–32)
- [ ] 7.4 Renumber 04-inventory/ files (12 files → 33–44)
- [ ] 7.5 Renumber 05-saveload/ files (9 files → 45–53)
- [ ] 7.6 Renumber 06-ui/ files (13 files → 54–66)
- [ ] 7.7 Renumber 07-narrative/ files (11 files → 67–77)
- [ ] 7.8 Renumber 08-weapons/ files (12 files → 78–89)
- [ ] 7.9 Renumber 09-ai/ files (9 files → 90–98)
- [ ] 7.10 Renumber 10-adaptive/ files (9 files → 99–107)
- [ ] 7.11 Renumber 11-meta/ files (6 files → 108–113)
- [ ] 7.12 Renumber 12-settings/ files (5 files → 114–118)
- [ ] 7.13 Renumber 13-polish/ files (10 files → 119–128)
- [ ] 7.14 Renumber 14-data-assets/ files (13 files → 129–141)

---

## Phase 8 — Update Cross-References

After renumbering, every internal cross-reference in every file must point to the correct filename.

- [ ] 8.1 Search all `.md` files for `](XX_` patterns
- [ ] 8.2 Verify each link target exists at the referenced path
- [ ] 8.3 Fix any broken or stale links

---

## Phase 9 — Update AUDIT_REPORT.md

- [ ] 9.1 Update all status columns to ✅ for previously missing/bundled systems
- [ ] 9.2 Update file counts (final: ~141 files, 0 missing)
- [ ] 9.3 Remove "Recommendations" section (all completed)
- [ ] 9.4 Add "Resolved" section documenting what was done

---

## Phase 10 — Update CONTEXT.md

- [ ] 10.1 Update directory structure to reflect all 14 directories
- [ ] 10.2 Update file count to ~141
- [ ] 10.3 Update build order to 14 phases
- [ ] 10.4 Update naming conventions reference
- [ ] 10.5 Mark Clean Slate refactoring as complete

---

## Phase 11 — Final Verification

- [ ] 11.1 Run `list_files` recursively on `docs/blueprints/` — verify 14 directories, ~141 files
- [ ] 11.2 Cross-reference: every Master system (Section 1–12) should have exactly 1 file
- [ ] 11.3 Cross-reference: all 20 Data Asset types from Section 13 have a spec
- [ ] 11.4 Verify no duplicate system names across directories
- [ ] 11.5 Verify all files follow TEMPLATE.md format (header, enums, structs, variables, functions, dispatchers, flow, communications, reuse)
- [ ] 11.6 Verify sequential numbering from 01 to 141
- [ ] 11.7 Run `git status` — should show renames, new files, deleted files, no orphaned files

---

## Phase 12 — Git Commit

- [ ] 12.1 Stage all changes
- [ ] 12.2 Commit with message: `refactor: clean slate — 1:1 master-to-file mapping for all 141 systems`
- [ ] 12.3 Verify commit is clean
- [ ] 12.4 (Optional) Create PR to main

---

## Notes for Execution Agent

1. **Use `apply_diff` for renaming file header lines** — change the `# XX_SystemName` line only
2. **Use `write_to_file` for creating new files** (always with complete content)
3. **Use `delete_file` for removing obsolete files**
4. **NEVER use `sed`, `awk`, or `cat >`** for file operations
5. **Read the Master document section** for each new file before writing it to get accurate variable/function definitions
6. **Follow TEMPLATE.md religiously** — every new file must have all required sections
7. **Commit after each Phase** (not after every file) to keep git history reasonable
8. **If a Master section is unclear on a detail**, use the conventions from nearby systems and document the assumption in Reuse Notes

---

*Checklist created 2026-05-18*