Titan

Use when working on 3D-specific rendering — deferred chain, G-buffer, clustered shading, Stratum GI, ReGIR, SVGF/A-SVGF, TAA, shadow techniques, depth/HZB, anything 3D-specific. ALWAYS load titan-rendering-core first; this skill assumes core conventions. Loads Titan-specific overrides for realtime-rendering. NOT for 2D rendering or editor panels.

Use when diagnosing a Titan renderer artifact — flicker, ghosting, fireflies, banding, light leaks, seams, boil, NaN/Inf, aliasing, smear/trails, dark voids, shadow artifacts, GI instability, denoiser/TAA issues. The frame-isolation-first debugging method: capture 60Hz, diff frames / A-B vs classical, consult literature, isolate via systematic-debugging, propose (and prove) a fix, record empirically. NOT for landing the production fix (hand to titan-rendering-3d-agent), 2D rendering, or editor panels.

Use when working in titan-rendering-frame-graph, titan-rendering-core, or titan-rendering-post-process-core — frame graph DAG, RenderTarget, DevicePool, PostProcessHook, CameraFrameData, HDR intermediate, tonemap, color management. Foundational layer shared between current 3D and future 2D rendering. Loads Titan-specific overrides for realtime-rendering. NOT for 3D-specific concerns (deferred chain, GI, shadows) — load titan-rendering-3d after this.

When a Titan bench tool using Renderer3d lacks on_resize → renderer.resize(), depth_prepass_view and HZB occlusion resources are never created — DepthPrepass, HzbBuild, and SceneCull passes silently skip, and taps produce no output

When adding a camera UBO shared between Rust and WGSL, verify field-by-field that the CPU layout matches the WGSL struct — especially packed vec4 fields where reordering silently breaks the shader

When building a depth prepass for reverse-Z HZB occlusion culling, use Greater compare (not Always) — the closest fragment must win so the HZB stores the nearest occluding surface, not the farthest

extract_draw_groups uses HashMap for draw batching, making group ordering non-deterministic across frames — the GPU AABB buffer and indirect draw commands use different indices each frame, causing `back_north` to be classified as `visible` on one frame and `hzb_occluded` on another for the same camera position

When depth prepass draw_indirect produces zero depth despite correct pipeline setup, force instance_count=1 on CPU to isolate buffer vs draw path issues, and add COPY_SRC to untappable textures for frame-level inspection

When draw_indexed_indirect produces only one visible object despite multiple groups having instance_count>0, suspect a wgpu bug where first_instance is ignored — all groups read instance 0 from a shared SSBO.

When designing a Titan rendering change, consult the realtime-rendering skill literature to validate architecture before presenting approaches to the user — never ask the user to choose between approaches the literature already answers.

When a Titan bench tool accepts --tap via titan_render_bench_common::TapArgs, BOTH the CLI field AND the wiring in on_start must be gated behind

Before debugging a gray/black bench frame, verify the camera Y-position matches scene geometry Y-level — a camera 20 units above ground looking horizontal sees nothing below the viewport, producing gray frames indistinguishable from rendering pipeline failures.

When QWEN.md auto-memory format/completeness keeps failing, close the gap with a PreToolUse hook that checks frontmatter (name/description/type) and MEMORY.md indexing — same pattern as todo_gate_guard

When adding GPU-driven culling passes to Titan, add standalone dispatch arms (DepthPrepass, SceneCull) WITHOUT modifying GBufferFill/MainForward draw code — keep the existing draw_indexed path intact, add draw_indirect as a separate step after baseline rendering is confirmed.

Before declaring any Titan work complete, run the 4-command CI gate — cargo check, fmt, clippy, nextest — and verify zero warnings outside vendored crates

textureSampleCompare is fragment-stage-only — compute shaders must use textureSampleCompareLevel with 4 params (no LOD, no offset). Also: bind group layouts must match pipeline stage visibility. When adding passes to shared RONs, all benches inherit them.

Pattern for reading back GPU SSBO data in Titan bench tools — staging buffer, copy_buffer_to_buffer, map_async, poll, visibility classification from indirect draw + bitmask buffers

Systematic pattern for cleaning code comments — strip process meta (Phase/Cluster/c-*/Stage/m*/cross-cluster labels, milestones), rewrite history as present constraints, convert pending/deferred language to TODO: markers, fix broken grammar, and log discovered TODOs to docs/TODO.md

When rendering/editor/streaming code changes lack documentation co-updates, enforce with a PreToolUse hook on git commit — checks staged diff for code vs doc coverage

When Titan frame-graph pass-ordering validation rules conflict with RON config files, RON configs are the authoritative source — fix the validation rule to match the RON

When adding a new Pass variant with DispatchKind::InlineRenderer to the Titan frame graph, update all synchronized sites — Pass enum, ALL_PASSES, manifest entry + resources, pipeline construction, dispatch arm, validation rules, canonical pin tests, all 8 RON configs, 3 bench tools

When adding a new Pass variant to the Titan frame graph, update all 10+ synchronized sites in lockstep — enum, ALL_PASSES, manifest, frame_graph_build, bench tools (3), RON configs, forward-only gates, scaffold dispatch, stratum_hook, render_hook

When a RenderQuality knob changes infrequently (at config load, not per-frame) and needs to reach a WGSL shader, use a specialization constant (override) set at pipeline creation rather than a UBO field — avoids UBO plumbing and per-frame write_buffer

After a rendering design is approved and before writing the implementation plan, run a structured compatibility check against the realtime-rendering skill's technique-compatibility.md, interactions.md, and the project's existing rendering architecture. Report PASS/GAP findings; fix gaps before proceeding.

When sub-agents keep straying outside the approved file list from the plan, close the gap with a PreToolUse hook that reads .qwen/task_scope.json — same pattern as rendering_naming_guard and todo_gate_guard

When QWEN.md // TODO: → docs/TODO.md tracking keeps failing, close the gap with a PreToolUse hook — same pattern as rendering_naming_guard for comment enforcement

When a resource (pool, pipeline, buffer) is already accessible via self in a StratumRenderHook dispatch method, do not route it through PassCtx — that would require adding a crate dependency from titan-rendering-3d to titan-stratum-lighting, breaking the trait-bridge decoupling

vec3<T> in WGSL uniform address space inherits vec4 alignment (16 bytes). When padding Rust

Activating compact storage formats (R16Float/Rg16Float) for denoiser AOVs requires coordinated BGL + WGSL + texture-format updates across writer and reader passes — change all in lockstep or the bind group will fail validation at runtime

When threading adapter capability flags from device creation through init-time constructors across crate boundaries, add a bool parameter to the constructor chain rather than trying to route through per-frame PassCtx — init-time allocations happen before per-frame dispatch and need the flag at construction time

Workflow for implementing a Tier-2 rendering technique in Titan: read the clean-room reference doc, write self-contained WGSL shaders with inlined helpers, follow the existing pass pattern (preblur.rs template), create pipeline structs + constructors + dispatch methods, wire into the frame-graph RON and StratumRenderHook trait

Compact storage formats (R16Float, R8Unorm, Rg16Float, Rg11b10Float) require a runtime probe at adapter creation for STORAGE_BINDING support. Desktop Vulkan/DX12/Metal always passes the probe. Mobile GPUs (older Mali/Adreno) may fail it — keep the probe and R32 fallback path. Never use compile-time gates — Titan ships one binary across platforms

When adding new mandatory fields to PassCtx, use replace_all on the closing }); pattern to add fields at all 22+ construction sites — then handle the 1-2 sites that don't match the common pattern separately

Canonical pattern for creating a new compute pipeline in Titan stratum-lighting — include_str WGSL, BGL entries, pipeline layout with Some(&bgl) and immediate_size:0, compute pipeline with cache:None

When adding STORAGE_BINDING to compact texture formats in vendored wgpu-types, both |s_ro_wo| flags and |TextureUsages::STORAGE_BINDING| in allowed_usages are needed — the flags element must include s_ro_wo or the HAL receives zero storage access bits

Titan WGSL shaders are self-contained — no

WGSL has no u16 or u8 types. Compact Rust structs with u16/u8 fields must NOT be mirrored with those types in WGSL — use u32 and pack/unpack manually, or fall back to f32. WGSL compilation panics with 'no definition in scope for identifier: u16'

How to start the brainstorming visual companion server on Windows and use it for UI brainstorming sessions.

Pattern for migrating a monolithic style module (style.rs) to a modular theme system with incremental panel migration in an egui-based editor.

Inspector polish patterns for reflection-driven property editors — right-aligned labels, drag-to-scrub, consistent spacing.