The datarim-doctor Skill — Keeping Operational Files Honest
How the datarim-doctor skill defines a thin one-liner contract for Datarim's operational indexes and runs an 8-pass migration to enforce it without losing a single task record.
As a project grows, tasks.md and backlog.md accumulate legacy block-style entries, stale sections, and rolling completion logs that bloat the context an agent reads at the start of every command. The datarim-doctor skill defines the canonical thin contract those files must hold and the migration algorithm that gets them there.
The thin index contract
Each line in tasks.md and backlog.md answers four questions — which task, what state, what complexity, and where the description file lives — and nothing else. The canonical format is a single bullet matching a strict regex: task ID, status, priority, level, title, and an arrow pointer to the description file. No prose, no sub-bullets, no inline requirements.
All task content lives in a separate file at datarim/tasks/{TASK-ID}-task-description.md. That file holds a 12-key YAML frontmatter block and up to 250 lines of body content across five fixed sections: Overview, Acceptance Criteria, Constraints, Out of Scope, and Related. The doctor enforces both the index line format and the description file schema.
The 8-pass migration
The migration script applies passes in a fixed sequence. Pass 0 rejects a ## Backlog section inside tasks.md — the doctor will not auto-migrate it because the semantic intent of each bullet is unknown. Pass 1 walks legacy block-style headings and extracts frontmatter fields from the body text, writing each to a new description file. Pass 2 rewrites the index files as thin one-liners. Pass 3 strips the abolished rolling-log sections from activeContext.md and deletes progress.md. Pass 4 migrates the legacy backlog-archive.md into per-task archive documents. Pass 6 strips archive sections from operational files. Pass 7 removes verified HTML comment markers that point to existing archive docs. Pass 5 re-scans the whole tree after the mutating passes to assert the result is compliant.
Data-loss safety contract
Every --fix invocation runs four safety rails before touching any file. A tarball of the entire datarim/ directory lands in /tmp before any mutation. A sidecar .pre-v2.bak copy sits next to each legacy file that Pass 4 migrates. A count invariant requires that the number of emitted task entries is at least as large as the number parsed — if the count drops, the script restores from the tarball and exits with code 2. A file lock prevents concurrent invocations from racing each other.
The idempotency guard means a second --fix on an already-compliant tree exits 0 immediately. The --quiet flag is used by /dr-init self-heal to check compliance without any output — just an exit code.
Why thin indexes matter
An agent reading a monolithic 100 KB tasks.md consumes context budget on content it does not need. The thin index cuts that read to under 1 KB. Task descriptions load on demand when a specific task is being worked. Completion history is never mirrored back into operational files — it lives only in documentation/archive/ and git log, where it belongs.
For the full operational file schema that the doctor enforces, see the datarim-system skill post. The /dr-doctor command wraps the migration script for interactive use.