From e702dec7a3b3c1f8d698efcbd7669bd80a1ab0c4 Mon Sep 17 00:00:00 2001 From: Erik Date: Thu, 21 May 2026 14:01:06 +0200 Subject: [PATCH] docs(O-T1): session handoff prompt for Phase O Task 1 (WB usage audit) Self-contained prompt for a fresh Claude Code session. The next session reads it once, has all the context it needs, produces the WB-usage closure audit at docs/research/2026-05-21-phase-o-t1-wb-audit.md, and stops before any extraction. Investigation-only (the /investigate skill applies). User reviews the audit before T2 begins. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/research/2026-05-21-phase-o-t1-prompt.md | 179 ++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 docs/research/2026-05-21-phase-o-t1-prompt.md diff --git a/docs/research/2026-05-21-phase-o-t1-prompt.md b/docs/research/2026-05-21-phase-o-t1-prompt.md new file mode 100644 index 0000000..3a5686c --- /dev/null +++ b/docs/research/2026-05-21-phase-o-t1-prompt.md @@ -0,0 +1,179 @@ +# Phase O — Task O-T1 — Session Handoff Prompt + +**Copy everything below the line into a fresh Claude Code session.** +The prompt is self-contained — the new session reads it once and has +all the context it needs. + +--- + +You are starting **Phase O — Task O-T1** on acdream. Phase O is **active** +(pre-empts M1.5 by user direction 2026-05-21). The full phase spec is at: + +``` +docs/superpowers/specs/2026-05-21-phase-o-dat-path-unification-design.md +``` + +**Read that spec first** (sections 1-4 are the most relevant to this task). +Also read the auto-loaded CLAUDE.md "Currently working toward: Phase O" block. + +## What you're doing + +Phase O extracts the WorldBuilder code we actually use into our own repo +so we can drop the project references and run with **one dat reader** +(`DatCollection`) instead of two. Task O-T1 is the safety pass that +must happen BEFORE any extraction: produce a closure of every WB type +and file we transitively use, so T2–T7 don't miss a dependency and +break the build at the "drop project references" step. + +**This is the `/investigate` skill territory — REPORT-ONLY.** Do not +move files, do not edit source, do not run `dotnet build/test`. Read +files, run read-only diagnostics (`grep`, `git`, `find`), and produce +a single markdown audit document. The user will review and approve +before any extraction starts in a later session. + +## Inputs available to you + +- **Our code that consumes WB**: + - `src/AcDream.App/Rendering/Wb/*.cs` — adapters that wrap WB. + Start with `WbMeshAdapter.cs` and `WbDrawDispatcher.cs`. + - `src/AcDream.App/Rendering/TerrainModernRenderer.cs` — uses some + WB types but is our own renderer. + - Anywhere else with `using WorldBuilder.*` or + `using Chorizite.OpenGLSDLBackend*`. Grep for both. +- **The WB source itself**: + - `references/WorldBuilder/WorldBuilder.Shared/` — types we use directly + - `references/WorldBuilder/Chorizite.OpenGLSDLBackend/` — the rendering code + we use (`ObjectMeshManager`, `TextureHelpers`, `SceneryHelpers`, + `LandSurfaceManager`, `OpenGLGraphicsDevice`, `Frustum`, etc.) +- **CSProj files** (the formal dependency boundary): + - `src/AcDream.App/AcDream.App.csproj` — has the WB ProjectReference entries + - `src/AcDream.Core/AcDream.Core.csproj` — same + +## Concrete steps + +1. **Direct-use enumeration.** Find every `using WorldBuilder.*` and + `using Chorizite.OpenGLSDLBackend*` line in `src/AcDream.*`. For each + file, list the specific WB types it references (e.g., + `ObjectMeshManager`, `OpenGLGraphicsDevice`, `TextureKey`, + `ObjectRenderBatch`). Don't forget `nameof()` and string references + in tests. + +2. **Transitive closure.** For each WB type in the direct-use set, open + its file in `references/WorldBuilder/` and list its dependencies on + *other* WB types. Walk the graph until closed. Be systematic — + `ObjectMeshManager` will pull on a lot. + +3. **Per-file inventory.** For each WB file in the closure: + - Path (relative to `references/WorldBuilder/`) + - Line count (`wc -l`) + - One-line role description + - Direct callers in our codebase (if any) or in WB (if transitive) + - Whether it touches `IDatReaderWriter` / `DefaultDatReaderWriter` + (these become DatCollection-swap candidates) + - Whether it touches GL state directly (matters for T3 — GL infra + extraction has different risk than dat-touching code) + +4. **Categorize by extraction task**. Bucket each file into one of: + - **T3 candidate** (texture / GL infrastructure, no dat dep) + - **T4 candidate** (mesh pipeline) + - **T5 candidate** (scenery / terrain blending) + - **T6 candidate** (EnvCell / portal) + - **NOT EXTRACTED** (we use it via project reference today but + can drop entirely — e.g., the WB editor tools, anything not in + our render path). Justify the "not extracted" call for each. + +5. **Hidden-dependency probes** (the things that bite at T7): + - Does WB use any `internal` types that are only accessible to + classes inside the WB project? If so, we'll have to make them + `public` or copy more. + - Does WB use any source generators, .targets files, or build + hooks that we'd need to replicate? + - Are there resource files (.png, .glsl, .shader) we need to copy? + - Does WB's `DefaultDatReaderWriter` differ from our `DatCollection` + in any behavioral way that would matter when we swap? (Caching, + thread safety, the same-file-different-handle thing, etc.) + Don't fully audit — just flag the questions. + +6. **Thread-model spot-check** (open question O-Q1 in the spec): + - Is `ObjectMeshManager` called from the render thread only, or + does our `LandblockStreamer` worker thread call into it? + `grep` for the call sites. If the worker thread reaches WB code, + flag it — we may have a latent race today that becomes obvious + after extraction. + +## Output + +Write the audit to: + +``` +docs/research/2026-05-21-phase-o-t1-wb-audit.md +``` + +Suggested structure: + +```markdown +# Phase O — Task O-T1 — WB Usage Audit + +## Direct use surface +(Table of (our file, WB types used)) + +## Transitive closure +(Tree or table walking from direct types through WB internals) + +## Per-file inventory +(Table: path, LOC, role, dat-touch?, GL-touch?, target task bucket) + +## Extraction-task mapping +- **T3 (GL infra):** N files, ~M LOC +- **T4 (mesh):** N files, ~M LOC +- **T5 (scenery/terrain):** N files, ~M LOC +- **T6 (EnvCell/portal):** N files, ~M LOC +- **NOT extracted:** N files, with justifications + +## Hidden-dependency risks +(Bulleted list of things flagged in step 5) + +## Thread-model finding +(Yes/no + evidence on whether WB is called from the worker thread) + +## Open questions for user +(Anything unclear that the user needs to call before T2 starts) +``` + +**Cap the audit doc at ~500 lines.** If the closure is bigger than that, +inline the per-file table for the top 30 files by LOC and link to a +separate appendix file for the long tail. + +## Acceptance for O-T1 + +- Audit doc exists at the path above. +- Every file in the closure is bucketed (T3 / T4 / T5 / T6 / NOT). +- Hidden-dependency risks section has at least the four items in + step 5 addressed (even if the answer is "none found"). +- No source code edited. No `dotnet build/test`. No project files + touched. (Verify with `git status` at the end — only the new + audit doc + maybe `git ls-files | grep WorldBuilder | wc -l`-style + diagnostic output should appear.) + +## When you're done + +Report back in chat with: + +1. Total LOC of the closure (the rough size of the extraction). +2. The bucket breakdown (how many files / LOC per task). +3. Any sharp edges flagged in the hidden-dependency risks section. +4. Your honest read on whether the 7-8 day estimate in spec §5 is + reasonable given what you found, or whether it needs a revision. + +**Then stop.** Do not start T2. The user reviews the audit before +extraction begins. + +## Reminders + +- You are operating under the `/investigate` skill rules (no edits). +- `references/WorldBuilder/` is the source to grep through, NOT to edit. +- WB is MIT-licensed; the eventual extraction is license-clean. You + don't need to think about that here. +- If something in the audit surfaces a reason Phase O shouldn't + proceed (e.g., WB has a license clause we missed, or the closure + is 50K LOC instead of 5K), say so clearly. We'd rather know now.