The /dr-archive Command — Closing a Task with a Permanent Record

Every completed task deserves a record that survives the session. /dr-archive is the final command in the Datarim pipeline: it converts a finished task into a permanent archive document, updates the index files, and removes the task from the active list.

Because archival writes are irreversible — the task moves from active to archived, index files change, and git state shifts — the command runs multiple guards before any mutation occurs.

The clean-git gate

Before anything is written, /dr-archive checks the git state of every repository touched by the task. On a dirty tree the operator picks one of three paths: commit the pending changes now, record the outstanding state in the archive document's Known Outstanding State section, or abort and return to /dr-do. Archiving silently over uncommitted work is not allowed.

For shared workspace repositories — where multiple parallel sessions may have staged unrelated changes — the check uses a script that classifies each modified file's hunks by task ID. Hunks belonging to other tasks are not a blocker; only the current task's own uncommitted work is flagged. This avoids false stops when parallel work is in flight.

What the archive document contains

The archive document is written to a path determined by the task's prefix. Each project prefix maps to a subdirectory under documentation/archive/, so every project's history stays together. The document has a fixed structure: initial task (one sentence from the operator brief), how it was resolved (one bullet per brief item), artefacts produced, and an Operator Handoff section that describes what a future session needs to know to pick up from this point.

A reflection pass runs internally as Step 0.5 of /dr-archive. It reviews the work, identifies lessons learned, and generates evolution proposals — Class A items that are presented for operator approval within the same archive cycle, or Class B items held until a PRD update is drafted. Class A proposals require explicit operator approval before being applied; they are not auto-applied.

Index updates

After the document is written, /dr-archive updates the Datarim index files. The task moves from the active list in tasks.md to the completed state, and activeContext.md is updated to reflect the new active-task count. Both files use a thin one-liner schema — no full task bodies in the index, just the metadata needed to route the next command.

Why the slash form matters

The archive document and all accompanying guards are only guaranteed to run when the canonical slash command form is used. Manually staging archive files or moving index entries by hand skips the pre-archive-check.sh and datarim-doctor.sh validators. The slash form is the contract — ad-hoc paths bypass it.

See the full pipeline context in what Datarim is, or read about the quality gate that runs just before archiving in /dr-compliance.