diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md index 476fd43..6a97157 100644 --- a/AGRARIAN_DEVELOPMENT_ROADMAP.md +++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md @@ -879,7 +879,7 @@ Target deliverable: A small group can join a server, spawn into one biome, gathe - [x] Define the MVP separation between knowledge, practical experience, physical stats, tools, and infrastructure. Added `Docs/KnowledgeAndSkillFoundation.md` with a five-part MVP model separating knowledge, practical experience, physical stats, tools, and infrastructure so basic survival remains possible but outcomes improve through understanding, practice, equipment, and durable world improvements. - [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. -- [ ] Define how knowledge affects survival actions: fewer mistakes, safer attempts, better yields, lower injury risk, and more reliable outcomes. +- [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. - [ ] Define how practical experience grows through use, repetition, mistakes, and recovery from failure. - [ ] Add first contextual learning prompts for fire safety, potable water, exposure, shelter placement, injury care, and resource identification. - [ ] Design optional knowledge checks that appear when relevant to the action instead of interrupting basic play. diff --git a/Docs/KnowledgeAndSkillFoundation.md b/Docs/KnowledgeAndSkillFoundation.md index 20201b0..0995398 100644 --- a/Docs/KnowledgeAndSkillFoundation.md +++ b/Docs/KnowledgeAndSkillFoundation.md @@ -123,3 +123,48 @@ Weather awareness: Taxonomy rule: skills are not unlock gates for basic MVP survival actions. They modify risk, quality, speed, yield, readability, and confidence. + +## Knowledge Effects On Survival Actions + +Knowledge should change outcomes in ways the player can understand. It should +not silently guarantee success or replace practical experience. + +Fewer mistakes: + +- Knowledge reduces obviously bad choices, such as placing fire near dry brush, + drinking unsafe water without treatment, building shelter in a drainage path, + ignoring nightfall, or using the wrong material for a recipe. +- The MVP expression is warning text, safer default prompts, and clearer failed + action reasons. + +Safer attempts: + +- Knowledge lowers the chance that an attempt creates injury, sickness, + uncontrolled fire, wasted materials, or exposure. +- The MVP expression is risk messaging and lower future failure modifiers once + the player has learned the relevant concept. + +Better yields: + +- Knowledge helps a character identify the useful part of a resource and avoid + damaging it during gathering, processing, or crafting. +- The MVP expression is improved expected yield or reduced waste where a system + already has yield/waste hooks. + +Lower injury risk: + +- Knowledge teaches safe handling, body mechanics, weather caution, fire + distance, tool choice, first-aid urgency, and when to stop working. +- The MVP expression is fewer avoidable injury checks and clearer warnings when + hunger, thirst, darkness, fatigue, or bad weather make work unsafe. + +More reliable outcomes: + +- Knowledge improves sequencing and condition checks before the action begins. +- The MVP expression is fewer failed crafts, safer shelter placement, better + fire maintenance, better water decisions, and more useful feedback after poor + results. + +Action-effect rule: knowledge should usually adjust probabilities, quality, +warnings, and explanation. It should only hard-block actions when the action +would be nonsensical without a discovered concept or required tool. diff --git a/Scripts/verify_knowledge_action_effects.py b/Scripts/verify_knowledge_action_effects.py new file mode 100644 index 0000000..9ac61f4 --- /dev/null +++ b/Scripts/verify_knowledge_action_effects.py @@ -0,0 +1,40 @@ +#!/usr/bin/env python3 +"""Verify knowledge effects on survival actions 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: [ + "## Knowledge Effects On Survival Actions", + "Fewer mistakes:", + "Safer attempts:", + "Better yields:", + "Lower injury risk:", + "More reliable outcomes:", + "Action-effect rule:", + ], + ROADMAP: [ + "[x] Define how knowledge affects survival actions: fewer mistakes, safer attempts, better yields, lower injury risk, and more reliable outcomes.", + ], +} + + +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: knowledge effects on survival actions are documented.") + + +if __name__ == "__main__": + main()