The /dr-doctor Command — Structural Health for Datarim Files
How /dr-doctor diagnoses and repairs Datarim operational files: migrating legacy block-style tasks to the thin one-liner schema, externalizing descriptions, and removing the obsolete progress.md.
Datarim operational files have a canonical structure. When tasks accumulate over months, that structure drifts: block-style headings mix with one-liner entries, description prose sprawls inside tasks.md, and an obsolete progress.md lingers from an earlier schema version. /dr-doctor fixes all of that.
The command is idempotent. Running it on a fully compliant project produces no output and exits cleanly. Running it on a legacy tree migrates every non-compliant file and then verifies the result — a second pass always returns zero findings.
When to run it
Three triggers bring /dr-doctor into the picture. The most common is manual: tasks.md or backlog.md has grown large or contains mixed-format entries. The second is automatic: /dr-init Step 0.6 runs a structural compliance probe and redirects here when it returns a non-zero exit. The third is after upgrading to Datarim v1.19.0 or later — the first run performs the schema migration.
The pre-archive check at /dr-archive also gates on compliance, so an uncleaned tree will surface here before any task can be closed.
Dry-run first, then apply
The default mode is dry-run. The command reports a four-row count table: legacy block-style headings, legacy bold-ID entries, non-compliant bullet lines, and whether progress.md still exists. If all counts are zero, the run exits silently. If findings are present, the command prompts before touching anything.
Pass --fix to apply the migration. Under the hood, scripts/datarim-doctor.sh acquires a file lock, writes atomically per file, and aborts with state preserved on any error. Post-migration, a second dry-run confirms zero findings.
What changes on disk
Each legacy block-style task entry in tasks.md or backlog.md becomes a single one-liner. The prose that was inside the block moves to a new file: datarim/tasks/{TASK-ID}-task-description.md with YAML frontmatter and body sections. If progress.md exists, its last-completed entries are promoted into activeContext.md and the file is deleted. Nothing outside datarim/ is touched.
After migration, a pass of the Init-Task Presence validator runs as an advisory check — it lists any tasks without an associated init-task file, flagged by age, but never blocks the migration itself.
Exit codes and recovery
Exit 0 means compliant or migration succeeded. Exit 1 means findings present in dry-run mode. Exit 2 means the migration aborted — state is preserved, and individual files can be rolled back with git restore. Exit 3 means a lock is held by a concurrent run; wait and retry. Exit 4 means a path-traversal guard fired — inspect the offending entry before proceeding.
Read more about the overall framework in what Datarim is, or see how framework components stay tidy with /dr-optimize.