Define knowledge action effects

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.

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.

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()