# Open Questions

Things we believe but couldn't fully verify in the first discovery pass, or that we observed but couldn't explain. Each question has a **verification path** - what would resolve it.

When a question gets resolved, move the answer into the relevant detail file (`architecture.md`, `agent-pipelines.md`, etc.) and delete the entry here. Or move it to `bugs-and-fixes.md` if it turned out to be a bug.

---

## Q1: Does `native_action_selector` always fire after dialogue, or only sometimes?

**Why we care:** Determines whether `embed_actions_in_dialogue: true` truly bypasses the native selector, or whether they run in parallel and fight for the action slot.

**What we observed:** The trace dump (`all_traces_1776478948530.json`) shows `mood_evaluation` and `memory_search_query_generation` after `generate_response`, but **no obvious `native_action_selection` span**. Either:

- (a) It's triggered on demand only when `embed_actions_in_dialogue: false` and didn't fire in the captured session.
- (b) It's named something else in the trace tree.
- (c) It was firing in parallel and the trace just didn't capture it under a recognizable name.

**Verification path:** Set `embed_actions_in_dialogue: false` in `SkyrimNet.yaml`, trigger an NPC dialogue, capture a fresh trace, look for new spans that weren't there before. If new `*action_evaluation*` spans appear, hypothesis (a) is confirmed.

---

## Q2: What's the actual GM polling timer source?

**Why we care:** We've been calling it "polling every ~30s" based on `gamemaster.continuousSceneCooldownSeconds`, but the trace doesn't show a clean periodic tick - fires correlate with events too.

**What we observed:** GM `gamemaster_evaluation` calls fire at irregular intervals in the captured logs. Sometimes ~30s apart, sometimes seconds after a player input or NPC event.

**Hypothesis:** The "polling" is actually event-driven - every relevant Skyrim event (per `Events.yaml` filters) triggers a GM evaluation, with `continuousSceneCooldownSeconds` as a *minimum* gap to prevent spam. So idle silence + cooldown = ~30s tick; active scene = much faster.

**Verification path:** Disable all event-triggered firings in `Events.yaml` (set `allowNPCReaction: false` everywhere), enable continuous mode, sit in an empty cell with no NPCs, watch trace timing. Should see clean 30s ticks if cooldown is the only timer.

---

## Q3: What does `defaults_manifest.json` actually do?

**Why we care:** Understanding the first-run / reset path is important for users restoring config.

**Hypothesis:** It's the schema the DLL seeds first-run config from. When a YAML doesn't exist, the DLL writes one populated from this manifest.

**Verification path:** Delete `overwrite/.../config/Memory.yaml` (a low-stakes one), launch Skyrim, check whether a fresh `Memory.yaml` regenerates with default values. If yes, hypothesis confirmed.

---

## Q4: Is `gamemaster.agentEnabled` distinct from `gamemaster.enabled`?

**Why we care:** Both default `true` in this install. If they're the same, that's tech debt; if they're different, we need to know what each gates.

**Verification path:** Toggle `agentEnabled: false` while keeping `enabled: true`, observe behavior. Then swap. Document whichever toggle changes what.

---

## Q5: Does `gamemaster_scene_planner` ever fire in current config?

**Why we care:** `prompts/gamemaster_action_selector.prompt:96-119` references a `scene_plan` context variable, suggesting a separate planner agent populates it. But the captured trace dump shows no `scene_planner` spans - either it never fires, or it fires under a different name, or it's gated behind an MCM toggle that's currently off.

**Verification path:** Search `Agents.yaml` for any scene_planner-related variant. Check MCM for a "Scene Planner" toggle. Enable if found, observe traces.

---

## Q6: What's the canonical decorator list?

**Why we care:** Decorators are the bridge from prompts to game state. Without the full list with signatures, we can't reason about what's possible to surface in a prompt.

**What we have:** ~30+ decorator names spotted in trace spans:
`decnpc`, `is_in_faction`, `is_player`, `is_in_combat`, `get_arousal_state`, `render_character_profile`, `render_subcomponent`, `format_event`, `short_time`, `get_name`, `get_nearby_npc_list`, `get_recent_events`, `get_quest_stage`, `is_narration_enabled`, `get_relevant_memories`, `get_scene_context`, `get_world_knowledge`, `papyrus_util`, `outfit_context`, …

**Verification path:** The full list is dynamically generated by the DLL via `prompts/documentation/main.prompt`. The in-game web UI's `/api/documentation` endpoint should expose the full enumeration with signatures. Hit that endpoint with `curl` against the local web server (port from `WebServer.yaml`).

---

## Q7: Where do contributing mods' YAML actions live on this disk?

**Why we care:** We claim they live in `/home/dafit/Games/Skyrim/nimmersky/mods/{ModName}/SKSE/Plugins/SkyrimNet/config/actions/*.yaml`, but we haven't enumerated the actual files in this install. Need this for the git-tracking plan.

**Verification path:** `find /home/dafit/Games/Skyrim/nimmersky/mods/ -name "*.yaml" -path "*/config/actions/*"`. List all paths, count by mod, sample one schema to confirm consistency with `action-system.md` description.

---

## Q8: What's IntelEngine doing exactly?

**Why we care:** It's a sibling SKSE plugin that registers 15 actions and has its own SQLite DB. We don't know its scope.

**What we have:** Plugin name suggests "intelligence" - possibly classification, world observation, scene tagging, or persistent narrative state.

**Verification path:** Check if IntelEngine ships its own README in the mod folder. Read its config files at `overwrite/.../config/plugins/IntelEngine/` (`factions.yaml`, `settings.yaml`). Inspect its action YAMLs to see what behaviors it registers.

---

## Q9: How does the SQLite vector_memory_system actually retrieve?

**Why we care:** The `0014_regenerate_embeddings` migration confirms an embedding pipeline. We know `all-MiniLM-L6-v2` is the embedding model. We don't know retrieval-time semantics: similarity threshold, top-K, recency weighting, faction filtering.

**Verification path:** Read `Memory.yaml` for tunables. Trace a `memory_search_query_generation` span end-to-end - the meta agent generates a query string, then the DLL must embed it, run a vector similarity search against the `vector_memory_system` table, and inject results into the dialogue context. Check the `SkyrimNet.log` for SQL query patterns.

---

## Q10: Knowledge Pack format (`0017_knowledge_packs` migration)

**Why we care:** dafit already authors `nimmerverse/nimmersky/oghma-sknpack/` knowledge packs (Whiterun, Winterhold, Solstheim, etc.). Understanding the runtime ingestion + storage format would let us validate that our packs are well-formed.

**Verification path:** Read `0017_knowledge_packs.sql` to see the table schema. Inspect an oghma-sknpack file to see the source format. Trace ingestion in `SkyrimNet.log` - search for "knowledge_pack" or "sknpack" patterns. The `oghma-proxy` tool probably has documentation we wrote ourselves.

---

## Q11: Does the chunker overlap suspicion for NPC↔NPC restatement still hold?

**Why we care:** During Bug #2 diagnosis we hypothesized `tts.maxSegmentWords: 4` might amplify chunker race conditions in NPC-NPC scenes. We later determined the GM-loop bug fully explained restatement and the chunker was innocent. But the small chunk size remains as a stress test for any other latent chunker bugs.

**Verification path:** Once Bug #2 is fixed, observe NPC-NPC scenes (Whiterun market with Ysolda↔Brenuin) with `maxSegmentWords` at 4 vs 24. If 4-word chunks cause clipping or audio gaps not seen at 24, the chunker has a chunk-size-dependent issue worth filing as Bug #4.

---

## Q12: How does the in-game prompt editor's `propose_prompt_edit` tool flow back into the override file?

**Why we care:** The runtime override at `overwrite/prompts/agent_chat.prompt.backup.1776372078` proves edits via the in-game LLM-driven prompt editor (`agent_prompt_helper.prompt`) get persisted with epoch-stamped backups. We don't know the exact write semantics - does it always backup-and-replace, or only on accept?

**Verification path:** Use the in-game prompt editor on a low-stakes prompt, watch what files appear/change in `overwrite/prompts/`. Document the backup naming and write-on-accept behavior.

---

## Conventions for adding new entries

- Number monotonically (Q13 next).
- Each entry needs **why we care** + **verification path** at minimum.
- If a question gets answered, *move the answer into the appropriate detail file* and delete the entry here. Don't let resolved questions pile up.
- If a question gets *partially* answered, update it with the partial answer and what's still unknown.
