diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md index 037e030..3d1401a 100644 --- a/AGRARIAN_DEVELOPMENT_ROADMAP.md +++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md @@ -881,7 +881,7 @@ Target deliverable: A small group can join a server, spawn into one biome, gathe - [x] Add a first-pass skill taxonomy for survival, gathering, tool use, crafting, fire, shelter, navigation, first aid, food safety, and weather awareness. Added the first MVP taxonomy to `Docs/KnowledgeAndSkillFoundation.md`, covering survival, gathering, tool use, crafting, fire, shelter, navigation, first aid, food safety, and weather awareness as non-lockout skill domains that modify risk, quality, speed, yield, readability, and confidence. - [x] Define how knowledge affects survival actions: fewer mistakes, safer attempts, better yields, lower injury risk, and more reliable outcomes. Added the knowledge action-effects model to `Docs/KnowledgeAndSkillFoundation.md`, defining how knowledge changes warnings, failed-action reasons, safety, yield/waste, injury risk, and outcome reliability without silently guaranteeing success or replacing practical experience. - [x] Define how practical experience grows through use, repetition, mistakes, and recovery from failure. Added practical experience growth rules to `Docs/KnowledgeAndSkillFoundation.md`, defining gain from meaningful use, diminishing returns for rote repetition, learning from readable mistakes, and extra credit for recovering well from failure. -- [ ] Add first contextual learning prompts for fire safety, potable water, exposure, shelter placement, injury care, and resource identification. +- [x] Add first contextual learning prompts for fire safety, potable water, exposure, shelter placement, injury care, and resource identification. Added first contextual prompt specs to `Docs/KnowledgeAndSkillFoundation.md` for fire safety, potable water, exposure, shelter placement, injury care, and resource identification, with trigger examples, prompt intent, sample wording, and the rule that prompts explain immediate risk without pausing the game or forcing a quiz. - [ ] Design optional knowledge checks that appear when relevant to the action instead of interrupting basic play. - [ ] Add player-facing feedback that explains why an action failed or produced poor results. - [ ] Define accessibility rules for the learning system: hints, retries, readable wording, no hard lockout from basic survival, and non-punitive practice paths. diff --git a/Docs/KnowledgeAndSkillFoundation.md b/Docs/KnowledgeAndSkillFoundation.md index 601c759..3586ee8 100644 --- a/Docs/KnowledgeAndSkillFoundation.md +++ b/Docs/KnowledgeAndSkillFoundation.md @@ -208,3 +208,64 @@ Recovery from failure: Experience gain rule: award experience for meaningful action plus context, apply diminishing returns to rote repetition, and give recovery credit when a player responds well to a mistake. + +## First Contextual Learning Prompts + +Contextual learning prompts should appear when the player is already interacting +with the relevant risk. They should be short, actionable, and easy to ignore +after the player understands the concept. + +Fire safety: + +- Trigger examples: placing or maintaining a campfire near dry brush, shelter, + wood piles, high wind, or long burn duration. +- Prompt intent: explain clearance, containment, maintenance, extinguishing, and + wildfire/structure risk. +- Example wording: "Clear space around open flame. Wind and dry fuel can spread + fire." + +Potable water: + +- Trigger examples: interacting with unknown water, drinking while sick, or + collecting water near contamination risk. +- Prompt intent: distinguish water access from safe drinking water. +- Example wording: "Water source found. Treating or boiling lowers sickness + risk." + +Exposure: + +- Trigger examples: nightfall, rain, wind, low body temperature, soaked state, + exhaustion, or leaving shelter/fire protection. +- Prompt intent: explain warmth, shelter, wind, rain, rest, and body temperature. +- Example wording: "Cold and wind drain warmth. Fire, shelter, dry clothes, and + rest reduce exposure." + +Shelter placement: + +- Trigger examples: placing shelter in drainage, exposed wind, steep slope, too + close to fire, or near unsafe terrain. +- Prompt intent: explain drainage, wind, fire distance, stability, and + weather-protection tradeoffs. +- Example wording: "Shelter works best on stable, drained ground away from open + flame." + +Injury care: + +- Trigger examples: bleeding, sprain, sickness, exhaustion, low health, or + continuing heavy work while injured. +- Prompt intent: explain stop-work decisions, rest, treatment, and worsening + risk. +- Example wording: "Treat bleeding and rest before heavy work. Exhaustion makes + mistakes more likely." + +Resource identification: + +- Trigger examples: first focus on wood, stone, fiber, edible plants, hide, or + water-related resources. +- Prompt intent: teach why the resource matters and what basic actions it + supports. +- Example wording: "Fiber is useful for binding, panels, and early shelter + parts." + +Prompt rule: contextual prompts should explain the immediate risk or opportunity +without pausing the game or forcing a quiz. diff --git a/Scripts/verify_contextual_learning_prompts.py b/Scripts/verify_contextual_learning_prompts.py new file mode 100644 index 0000000..0e266dd --- /dev/null +++ b/Scripts/verify_contextual_learning_prompts.py @@ -0,0 +1,41 @@ +#!/usr/bin/env python3 +"""Verify first contextual learning prompts are documented.""" + +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +DOC = ROOT / "Docs" / "KnowledgeAndSkillFoundation.md" +ROADMAP = ROOT / "AGRARIAN_DEVELOPMENT_ROADMAP.md" + +REQUIRED = { + DOC: [ + "## First Contextual Learning Prompts", + "Fire safety:", + "Potable water:", + "Exposure:", + "Shelter placement:", + "Injury care:", + "Resource identification:", + "without pausing the game or forcing a quiz", + ], + ROADMAP: [ + "[x] Add first contextual learning prompts for fire safety, potable water, exposure, shelter placement, injury care, and resource identification.", + ], +} + + +def main() -> None: + missing: list[str] = [] + for path, snippets in REQUIRED.items(): + text = path.read_text(encoding="utf-8") + for snippet in snippets: + if snippet not in text: + missing.append(f"{path.relative_to(ROOT)} missing {snippet!r}") + if missing: + raise SystemExit("FAILED: " + "; ".join(missing)) + print("OK: first contextual learning prompts are documented.") + + +if __name__ == "__main__": + main()