diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md index 6a97157..037e030 100644 --- a/AGRARIAN_DEVELOPMENT_ROADMAP.md +++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md @@ -880,7 +880,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. - [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. +- [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. - [ ] 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. diff --git a/Docs/KnowledgeAndSkillFoundation.md b/Docs/KnowledgeAndSkillFoundation.md index 0995398..601c759 100644 --- a/Docs/KnowledgeAndSkillFoundation.md +++ b/Docs/KnowledgeAndSkillFoundation.md @@ -168,3 +168,43 @@ More reliable outcomes: 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. + +## Practical Experience Growth + +Practical experience should grow from meaningful work, not from standing still +or repeating a zero-risk input forever. It is the record of a character learning +how a task feels in the world. + +Use: + +- Experience increases when a character performs a real survival action with + cost, time, context, and outcome. +- Good candidates include gathering, tool use, crafting, fire maintenance, + shelter placement, navigation decisions, first aid, food preparation, and + weather-response choices. + +Repetition: + +- Repetition improves consistency, but repeated identical low-stakes actions + should give diminishing returns. +- Variation should matter: different weather, darkness, tools, materials, + terrain, injury state, and resource types teach more than the same easy action. + +Mistakes: + +- Mistakes can teach when they have a readable cause and the player receives + feedback. +- Failed crafts, wasted resources, unsafe fire placement, bad shelter sites, + injury, sickness, and exposure should create learning opportunities if the + player can understand what happened. + +Recovery from failure: + +- Recovering from a bad outcome should teach more than simply failing. +- Examples include extinguishing a risky fire, treating bleeding, finding safer + water, rebuilding a weak shelter, resting after exhaustion, and changing route + after getting lost. + +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. diff --git a/Scripts/verify_practical_experience_growth.py b/Scripts/verify_practical_experience_growth.py new file mode 100644 index 0000000..a26409f --- /dev/null +++ b/Scripts/verify_practical_experience_growth.py @@ -0,0 +1,40 @@ +#!/usr/bin/env python3 +"""Verify practical experience growth rules 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: [ + "## Practical Experience Growth", + "Use:", + "Repetition:", + "Mistakes:", + "Recovery from failure:", + "Experience gain rule:", + "diminishing returns", + ], + ROADMAP: [ + "[x] Define how practical experience grows through use, repetition, mistakes, and recovery from failure.", + ], +} + + +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: practical experience growth rules are documented.") + + +if __name__ == "__main__": + main()