diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md index 3c827aa..059e7ef 100644 --- a/AGRARIAN_DEVELOPMENT_ROADMAP.md +++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md @@ -885,7 +885,7 @@ Target deliverable: A small group can join a server, spawn into one biome, gathe - [x] Design optional knowledge checks that appear when relevant to the action instead of interrupting basic play. Added optional knowledge-check rules to `Docs/KnowledgeAndSkillFoundation.md`, defining inline/skippable presentation, action-relevant timing, calm review moments, non-punitive wrong answers, and the rule that checks deepen understanding without gating the first survival loop. - [x] Add player-facing feedback that explains why an action failed or produced poor results. Added failed-action and poor-result feedback rules to `Docs/KnowledgeAndSkillFoundation.md`, requiring short messages that say what happened, name one likely cause, offer one useful next step, avoid blame, and avoid revealing hidden formulas. - [x] Define accessibility rules for the learning system: hints, retries, readable wording, no hard lockout from basic survival, and non-punitive practice paths. Added learning accessibility rules to `Docs/KnowledgeAndSkillFoundation.md`, covering reusable hints, retries, readable wording, non-color-only warnings, no lockout from basic survival, safer practice paths, and diminishing returns to prevent exploit loops. -- [ ] Define the first subject content format: topic, concepts, difficulty tier, prerequisite concepts, in-game effect, practice action, and source note. +- [x] Define the first subject content format: topic, concepts, difficulty tier, prerequisite concepts, in-game effect, practice action, and source note. Added a compact subject content schema to `Docs/KnowledgeAndSkillFoundation.md` with `topic`, `concepts`, `difficulty_tier`, `prerequisite_concepts`, `in_game_effect`, `practice_action`, and `source_note`, plus a fire-clearance example suitable for later data assets. - [ ] Add a small MVP question bank for elementary survival knowledge. - [ ] Define when deeper questions should matter: quality improvements, safer work, complex crafting, teaching others, and advanced branches. - [ ] Add design notes for avoiding exploit farming and rote memorization. diff --git a/Docs/KnowledgeAndSkillFoundation.md b/Docs/KnowledgeAndSkillFoundation.md index 4e489ab..06ec7bb 100644 --- a/Docs/KnowledgeAndSkillFoundation.md +++ b/Docs/KnowledgeAndSkillFoundation.md @@ -379,3 +379,35 @@ Non-punitive practice paths: Accessibility rule: learning should make players more capable without making them feel trapped, shamed, or forced into a classroom flow. + +## Subject Content Format + +Learning content should use a small structured format so topics can become data +assets later without rewriting design intent. + +Required fields: + +- `topic`: stable identifier and display name, such as `fire.clearance`. +- `concepts`: one or more concept tags the player may learn or demonstrate. +- `difficulty_tier`: `elementary`, `practical`, `advanced`, or `expert`. +- `prerequisite_concepts`: concept tags that should be known first, if any. +- `in_game_effect`: the warning, modifier, feedback, unlock, or quality effect + this topic can influence. +- `practice_action`: the action that can build practical experience for the + topic. +- `source_note`: a short design/source note explaining why the topic matters. + +Example: + +```text +topic: fire.clearance +concepts: fire_safety, dry_fuel, wind_spread +difficulty_tier: elementary +prerequisite_concepts: none +in_game_effect: clearer fire-risk warning and lower unsafe-placement mistakes +practice_action: clear area, contain fire, maintain fire, extinguish fire +source_note: Open flame near dry fuel and wind can spread beyond the campfire. +``` + +Format rule: content records should be small enough to review in source control +and explicit enough to become data assets later. diff --git a/Scripts/verify_subject_content_format.py b/Scripts/verify_subject_content_format.py new file mode 100644 index 0000000..da98f37 --- /dev/null +++ b/Scripts/verify_subject_content_format.py @@ -0,0 +1,43 @@ +#!/usr/bin/env python3 +"""Verify the first subject content format is documented.""" + +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +DOC = ROOT / "Docs" / "KnowledgeAndSkillFoundation.md" +ROADMAP = ROOT / "AGRARIAN_DEVELOPMENT_ROADMAP.md" + +REQUIRED = { + DOC: [ + "## Subject Content Format", + "`topic`", + "`concepts`", + "`difficulty_tier`", + "`prerequisite_concepts`", + "`in_game_effect`", + "`practice_action`", + "`source_note`", + "topic: fire.clearance", + "Format rule:", + ], + ROADMAP: [ + "[x] Define the first subject content format: topic, concepts, difficulty tier, prerequisite concepts, in-game effect, practice action, and source note.", + ], +} + + +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: subject content format is documented.") + + +if __name__ == "__main__": + main()