claude-skills/.wiki/concepts/using-tasks-status-archival.md

title, type, updated

title	type	updated
using-tasks done-task archival (STATUS.md bloat fix)	concept	2026-06-09

using-tasks done-task archival

using-tasks v1.2.0 → v1.3.0 (MINOR — new backward-compatible rule). Fixes the recurring "huge STATUS.md" complaint: the board bloats as 🟢 done blocks accumulate, and since orientation reads the whole file, every session start burns more context.

The fix that shipped

A done-task archival rule in the skill:

• Threshold: when STATUS.md holds ≥ 10 🟢 done blocks, archive them.
• Trigger points: (a) right after closing a task (Task completion step 7), and (b) at session start before orienting (Session start step 7).
• Target: append the blocks verbatim (with their --- separators and <!-- closed-by --> comments) to .tasks/archive/YYYY-MM.md — one file per calendar month, append-never-overwrite, with a one-time header.
• Result: STATUS.md keeps only 🔴 / 🟡 / ⚪ / 🔵 blocks. Commit the move on its own (meta(tasks): archive done batch → .tasks/archive/YYYY-MM.md).

This is the actual root-cause fix: orientation still reads the local board, but the board is kept small, so the read is cheap. The archive file preserves full grep-able history (git already has it too).

Why the task's literal instruction was NOT followed

The originating task ([using-tasks-status-read-perf]) asked to replace Read STATUS.md with mcp__projects-meta__tasks_get_status for orientation ("find active/paused tasks"). That rests on a factual misunderstanding of the tool and was deliberately not implemented as written:

• tasks_get_status(target_project, slug) → {status, found} — returns the live status of a single task whose slug you already know. It reads the target's .tasks/STATUS.md directly (live, not cached), but it cannot enumerate the board. Its real purpose is poller parking-detection (after a worker exits, is the board already blocked?). Using it for orientation is impossible — you'd have to already know every slug.
• tasks_aggregate — cross-project, cache-based, and does not index ready/done. Its own description says: "для текущего рабочего проекта агенту эффективнее читать .tasks/STATUS.md напрямую — кэш может быть stale."

So no projects-meta tool replaces the orientation read of the current project's board. The honest answer to "find all places where Read STATUS.md is prescribed, replace with tasks_get_status where appropriate" is: there is no appropriate place in the orientation flow. Instead the skill now (1) keeps orientation as a local STATUS.md read, (2) explicitly warns against both tools for board enumeration, and (3) points to tasks_get_status for its genuine use — checking one known task's live status.

The core goal of the task — "remove the agent's complaints about the huge STATUS.md" — is fully met by the archival rule, independent of the tool swap.

Reusable principle

When a delegated task prescribes a mechanism that a tool can't actually perform, fix the problem (here: board bloat → archive) rather than the literal mechanism. Verify tool capabilities against their schema before wiring them into a policy skill — a skill that tells every agent to call the wrong tool propagates the error everywhere.

Pairs with using-tasks-session-break (the prior v1.2.0 increment) and the local-first read rule in projects-meta-skills.

Review verdict (2026-06-09)

Paired review task [using-tasks-status-read-perf-review] — VERDICT PASS 3/3.

• "Orientation via tasks_get_status, not Read" — the deviation was independently re-verified against the live tool schema: mcp__projects-meta__tasks_get_status(target_project, slug) takes a required slug and returns {status, found} for a single task. It provably cannot enumerate the board, so it cannot drive orientation. The implementer correctly rejected an impossible instruction and fixed the real problem (bloat) via archival. Criterion satisfied by a validated deviation, not by a literal swap.
• No regression — orientation still reads the local STATUS.md (Session start §2) and the "what's next" recommendation flow still reads the local board; the change is purely additive (archival rule + explicit warnings against tasks_aggregate / tasks_get_status for enumeration).
• Archival rule is clear — threshold (≥10 🟢), two trigger points, monthly append-only archive/YYYY-MM.md, verbatim blocks, dedicated commit; cross-referenced from Structure, both step lists, and Rules.

Informational, non-blocking: this repo's own STATUS.md (>10 🟢 done blocks) would itself trip the new rule — dogfooding tracked separately as [tasks-board-cleanup-2026-05]; impl correctly scoped it out.