Docs: Implement Tone Damping, Cultural Calibration, and The Accountability Handbook

Author: darestack

docs/guides/managers.md

@@ -0,0 +1,33 @@
+# The Accountability Handbook: A Guide for Managers 👔
+
+CommitGuard AI is a tool of empowerment, not surveillance. For a Human-in-the-Loop (HITL) system to work, managers must know how to translate AI flags into professional leadership.
+
+---
+
+## 1. Interpreting the Flags
+When CommitGuard flags an **"Ambiguity"** or a **"Truth Gap,"** it is a prompt for a conversation, not a citation for failure.
+
+*   **Flag: "Ambiguous Commitment"**
+    *   *AI Logic*: The user's words were too vague to extract a deadline.
+    *   *Manager Action*: Don't scold. Instead, reply: *"Hey [Name], I saw your update. To help me clear any blockers, could you give me a rough target for when you'll have this in review?"*
+    *   *Goal*: Precision, not pressure.
+
+*   **Flag: "Truth Gap Detected"**
+    *   *AI Logic*: Verbal claims don't match Git evidence.
+    *   *Manager Action*: Assume there is a technical blocker. Ask: *"I noticed the repo hasn't updated since our chat. Are there any local environment issues or merge conflicts I should jump in on?"*
+    *   *Goal*: Removing blockers, not investigating honesty.
+
+---
+
+## 2. Managing the "Human-in-the-Loop" (HITL)
+High-stakes interventions should never be 100% autonomous.
+
+1.  **Review the Confidence Score**: If the AI has a `confidence_score` of 0.8 but flags a high risk, verify if the user's recent Slack messages were sarcastic or high-context.
+2.  **Calibrate for Morale**: If the team has just finished a "Death March" (long sprint), manually increase the **Supportive Threshold** to allow for natural recovery.
+3.  **Cross-Cultural Norms**: Ensure your specific team's "Directness Level" is reflected in the agent's tone settings.
+
+---
+
+## 3. Best Practices for Professionalism
+*   **Public vs. Private**: CommitGuard monitors public channels, but follow-up interventions for **high-risk signals** should often be moved to a 1-on-1 private DM thread once the manager is alerted.
+*   **Celebrate the Reliability**: When someone consistently hits 100% on their Reliability Score, use the report as a basis for formal recognition. Accountability is as much about **Praise** as it is about Progress.

docs/overviews/ethics.md

@@ -9,9 +9,16 @@ One of our most discussed features is the **"Confrontational"** tone. Here is ho
 
 *   **The Empathy Buffer**: The system is hardcoded to prioritize `SUPPORTIVE` tones if anything resembling burnout or personal distress is detected.
 *   **The Burnout Safety Valve**: If the `ExcuseDetector` identifies signs of fatigue, the system **blocks** confrontational escalation and triggers a "Burnout Alert" for the manager instead. 
-*   **Tone as Calibration, Not Punishment**: The objective isn't to "scold" but to match the professional urgency required by the deadline.
+*   **Tone Drift & Cooling-off**: To prevent morale fatigue, the system implements **tone-damping**. If a user has received multiple "Firm" follow-ups, the system enters a 48-hour "Cooling-off" state where only supportive or neutral tones are permitted to avoid wearing down the individual.
+
+## 2. Cultural & Contextual Sensitivity
+"Deflection" is relative. What is seen as blunt in one culture is polite in another:
+
+*   **Sensitivity Calibration**: CommitGuard supports **Cultural Tone Profiles**. Managers can calibrate the "Pressure Sensitivity" of the agents to match their specific team norms (e.g., High-Directness vs. High-Context locales).
+*   **Domain-Specific Jargon**: The NLP models are refined to recognize that certain industry vernacular (e.g., *"I'm swamped"*) may be a routine status update rather than an excuse in specific high-velocity teams.
+
+## 3. Privacy & Data Integrity
 
-## 2. Privacy & Data Integrity
 Monitoring at the granularity of Slack threads and Git commits requires a strict privacy stance:
 
 *   **Scoped Monitoring**: CommitGuard is designed to monitor designated `#project` channels, not private DMs or unrelated chatter.

mkdocs.yml

@@ -60,6 +60,8 @@ nav:
       - Quick Start: guides/quickstart.md
       - Slack Integration: guides/slack.md
       - GitOps Accountability: guides/gitops.md
+      - The Accountability Handbook: guides/managers.md
+
 
   - API Reference:
       - Endpoint Specs: reference/api.md