# Michat Docs Drift Guard

> Prevent documentation drift in the MiChat repo. Use when editing any docs, preparing a release/clean-history pass, or when docs disagree. Enforces: (1) `docs/` is canonical and mirrored into `profiles/assistant/library/michat-specs/`, (2) `docs/MICHAT_REFERENCE.md` is human-facing and must not contradict technical docs or code, (3) assistant-facing guides under `profiles/_global/library/*_for_assistants.md` are derived and must not contradict sources or code, and (4) version/date headers should be bumped when docs change.

- Skill: `filmicgaze/michat-docs-drift-guard` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add filmicgaze/michat-docs-drift-guard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/filmicgaze/michat-docs-drift-guard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: filmicgaze (https://skillmd.com/u/filmicgaze)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/filmicgaze/michat-docs-drift-guard

---


# MiChat Docs Drift Guard

## Canonical Rules

- Code is ground truth when ambiguous: `michat/` and toolset configs.
- Canonical documentation lives in `docs/`.
- `profiles/assistant/library/michat-specs/` must be an exact mirror of `docs/` (same filenames, same contents).
- `docs/MICHAT_REFERENCE.md` is human-facing and can be higher-level, but must not contradict `docs/` or code.
- `profiles/_global/library/operating_guide_for_assistants.md` and `profiles/_global/library/troubleshooting_for_assistants.md` are derived assistant guides and must not contradict their named sources or code.

## Update Workflow (Use This Order)

1. Verify truth if needed
   - If changing paths, defaults, gates, UI labels, or dev/frozen behavior: confirm by reading the relevant code.
2. Update canonical docs
   - Edit the owning file(s) under `docs/`.
3. Update the human-facing guide
   - If the change affects a user-visible behavior or concept, update `docs/MICHAT_REFERENCE.md`.
   - Keep it readable; remove minutiae, not facts.
4. Update derived assistant guides
   - If assistants rely on the claim for operations/troubleshooting, update the derived guides.
   - Keep “Derived from:” lines consistent with the current source versions/dates.
5. Bump version/date headers
   - If a doc has a `— vX.Y.Z — YYYY-MM-DD` header, update date whenever the change is user-meaningful.
   - Bump version for non-trivial changes, following the repo’s existing pattern (do not invent a new scheme).
6. Resync the mirror
   - Copy `docs/*.md` to `profiles/assistant/library/michat-specs/*.md`.
   - Verify the mirror matches exactly (hash or diff).

## Drift Checks (Fast, Deterministic)

### 1) Mirror equality (hash check)

```powershell
$docsDir = 'docs'
$mirrorDir = 'profiles/assistant/library/michat-specs'
$docNames = (Get-ChildItem -LiteralPath $docsDir -File | Sort-Object Name).Name
foreach ($name in $docNames) {
  $h1 = (Get-FileHash -Algorithm SHA256 -LiteralPath (Join-Path $docsDir $name)).Hash
  $h2 = (Get-FileHash -Algorithm SHA256 -LiteralPath (Join-Path $mirrorDir $name)).Hash
  if ($h1 -ne $h2) { Write-Output ("DRIFT " + $name) }
}
```

### 2) Spot-check a single file (diff)

```powershell
git --no-pager diff --no-index -- docs/MICHAT_REFERENCE.md profiles/assistant/library/michat-specs/MICHAT_REFERENCE.md
```

## High-Risk Claim Types (Always Verify In Code)

- Paths: data root, profiles root, credentials root, frozen vs dev locations
- Gates: what enables a toolset vs what toggles a permission
- UI exact text: Settings labels, buttons, tooltips
- Allow-lists: file extensions, blocked actions, safety restrictions

When editing these, prefer citing/aligning to the exact module (e.g., `michat/runtime_paths.py`, `michat/toolsets/*/__init__.py`, `michat/qt_shell.py`).