Add failed action feedback rules

AGRARIAN_DEVELOPMENT_ROADMAP.md

@@ -883,7 +883,7 @@ Target deliverable: A small group can join a server, spawn into one biome, gathe
 - [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.
 - [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.
 - [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.
-- [ ] Add player-facing feedback that explains why an action failed or produced poor results.
+- [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.
 - [ ] Define accessibility rules for the learning system: hints, retries, readable wording, no hard lockout from basic survival, and non-punitive practice paths.
 - [ ] Define the first subject content format: topic, concepts, difficulty tier, prerequisite concepts, in-game effect, practice action, and source note.
 - [ ] Add a small MVP question bank for elementary survival knowledge.

Docs/KnowledgeAndSkillFoundation.md

@@ -304,3 +304,37 @@ Outcome rules:
 
 Knowledge-check rule: checks should deepen understanding and improve outcomes,
 not gate the first survival loop.
+
+## Failed-Action And Poor-Result Feedback
+
+When an action fails or produces a poor result, the player should receive a
+plain explanation that points to the likely cause and next useful response. The
+message should be short enough to read during play.
+
+Feedback should identify:
+
+- missing or unsuitable materials;
+- unsafe weather, darkness, terrain, or exposure;
+- low stamina, hunger, thirst, injury, sickness, or exhaustion;
+- poor tool choice or damaged tools;
+- low knowledge, low practical experience, or missed prerequisite concept;
+- invalid placement, fire risk, drainage risk, blocked access, or instability;
+- normal uncertainty when the game intentionally does not reveal exact odds.
+
+Message style:
+
+- Say what happened.
+- Name one likely cause.
+- Offer one useful next step.
+- Avoid blaming the player.
+- Avoid revealing hidden formulas or exact random rolls.
+
+Example messages:
+
+- "The fire catches poorly. Damp fuel and wind are making ignition unreliable."
+- "The shelter frame feels unstable. Flatter, drained ground would help."
+- "You waste some fiber. More practice with binding would improve the result."
+- "Your hands shake from exhaustion. Rest or food would make this safer."
+
+Feedback rule: poor results should teach the player what to try next without
+turning every failure into a lecture.

Scripts/verify_failed_action_feedback_rules.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""Verify player-facing failed-action feedback 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: [
+        "## Failed-Action And Poor-Result Feedback",
+        "Feedback should identify:",
+        "Message style:",
+        "Say what happened.",
+        "Name one likely cause.",
+        "Offer one useful next step.",
+        "Feedback rule:",
+    ],
+    ROADMAP: [
+        "[x] Add player-facing feedback that explains why an action failed or produced poor results.",
+    ],
+}
+
+
+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: failed-action feedback rules are documented.")
+
+
+if __name__ == "__main__":
+    main()