--- name: docs-archive description: Rotate closed entries (Status: Fixed/Resolved/Won't fix/Superseded by X) from active `_ISSUES.md` / `_TODO.md` / `LLM_PROTOCOL_DECISIONS.md` files into year-bucketed archive companions (`*_.md`). Year of the Status update determines destination file. Active files retain only Open/Partially Fixed entries plus a header pointer to the archives. Archive files are NOT auto-loaded by `docs-discovery`; agents read them on-demand when historical context becomes relevant. Invoke explicitly ("archive ISSUES", "rotate logs") or via LLM-suggest-back when a loaded file shows many closed prior entries. compatibility: Designed for Claude Code and GitHub Copilot (VS). Uses the host agent's Read/Write/Edit/Glob/Grep tools. metadata: author: Fullepi --- # docs-archive Lifecycle skill for the workspace's append-only artifact files. Active files grow without bound as work accumulates; this skill consolidates closed entries into year-bucketed archive companions, keeping the active file as a focused "what's still open" view. ## When to invoke ### Explicit user triggers - "archive ISSUES" / "archive TODOs" / "archive decisions" / "rotate logs" - "consolidate closed entries" - "archive {TOPIC}" — narrowed to a specific topic ### LLM-suggest-back (you flag, user confirms) When a `_ISSUES.md` / `_TODO.md` / `LLM_PROTOCOL_DECISIONS.md` file is loaded and you observe: - Many closed entries (Fixed/Resolved/Won't fix/Superseded by X) still in the active file - The file is long enough that loading has noticeable token cost - Closed-to-open ratio is high (e.g., > 50% closed) Phrase: *"`LOGGING_ISSUES.md` has N closed entries (Fixed/Resolved/...) still in the active file — consider running `docs-archive` to consolidate into year-bucketed archives. (Confirm if you want me to invoke.)"* User confirmation required. Never auto-invoke. ### When NOT to invoke - File has only a few entries — overhead exceeds benefit - File has no closed entries — nothing to move - User is mid-investigation referencing entries that may be archived — defer until done ## Archive criterion (single rule) Move entry X to archive IF `Status: Closed`. Year derived from a date in the entry body (e.g., `Fixed 2026-04-25`, `Won't fix 2026-04-25`, `Superseded by LOG-I-X 2026-04-25`). If no parseable date in body, default to current year. **Stay in active file**: - `Status: Open` — including documented-current-behaviour entries (these stay Open with a body callout per `TOPIC_CODES.md`'s Status field conventions) - `Status: InProgress` - Any entry without parseable Status (treat as Open; flag to user) **Foundational LLMP-DEC entries**: protocol-meta decisions describing CURRENTLY-ACTIVE rules typically have no Status field — they stay in the active file naturally. If later superseded, they get `Status: Closed` and become archive-eligible normally. ## Step 1 — Identify scope Glob the workspace for active artifact files (exclude existing year-suffixed archives): ``` **/{TOPIC}_ISSUES.md **/{TOPIC}_TODO.md **/LLM_PROTOCOL_DECISIONS.md ``` Default scope: all matches. Optionally narrow per user: "just LOGGING", "just DEC log", "just primary repos". ## Step 2 — Per-file analysis (read-only) For each candidate file, report: | Field | Example | |---|---| | Total entries | 17 | | Status: Open | 9 | | Status: Partially Fixed | 1 | | Status: Documented limitation | 1 | | Closed (archive-eligible) | 6 | | ↳ broken down by year (Status update) | 2025: 3, 2026: 3 | Show the user a summary table covering all candidate files. ## Step 3 — User selects scope User indicates: "all eligible" / "just {TOPIC}" / "skip {file}" / "year ≥ {N}". If unclear, ask: *"process all 4 files (LOG, BIN, SIG, DEC)? Or narrow?"* ## Step 4 — Generate archive plan (still no writes) For each affected file: 1. **Build archive file content** for each year present: - Filename: `_.md` (e.g., `LOGGING_ISSUES_2025.md`) - Header (2 lines): topic + "Archived entries (Status: closed) from ``. IDs preserved (never reassigned). Format identical to active file." - Entries: closed entries from that year, in original chronological/ID order. 2. **Build new active file content**: - Original header preserved. - **Insert a pointer block immediately after the header**: ``` > **Archived entries**: see `_2025.md`, `_2026.md` (closed entries by year). > Archive files are not auto-loaded — read on demand if relevant context is suspected (regression hint, supersession reference). ``` - Remaining entries: only Open / Partially Fixed / Documented limitation / unknown-status. 3. **Show diff** for each affected file (or summary if very large). ## Step 5 — Apply with explicit consent (Rule #5) On explicit user approval: 1. `Write` archive files (new); `Edit` for any pre-existing archive files being extended. 2. `Edit` active files: remove archived entries, add pointer block. 3. Verify: re-read counts, confirm entries arrived intact. ## Step 6 — Cross-reference verification `Grep` archived IDs in: code (`*.cs`), other `.md` files. Report any references — but **do not auto-rewrite**. IDs are preserved; `docs-discovery`'s on-demand archive read finds them when needed. ## Step 7 — Decision Log archive case If `LLM_PROTOCOL_DECISIONS.md` was archived: - "Current protocol state" summary at top stays in active file unchanged. - Dated table rows for `Superseded by` entries move to `LLM_PROTOCOL_DECISIONS_.md`. - Yearly archive convention already documented (LLMP-DEC governance section). ## Edge cases - **No closed entries anywhere**: exit cleanly with "no archive-eligible entries found across N candidate files". - **Status field missing/malformed**: flag the entry; treat as Open; user decides. - **Year unparseable from Status**: default to current year; flag for user fix-up. - **Existing archive contains an ID we're about to add**: should never happen if IDs append-only and Status monotonic. Abort with explicit error — manual review. - **Active file becomes empty**: keep file with header + pointer. Do not delete. - **Concurrent edits / dirty git**: prompt user before proceeding. ## Tool usage Tool-neutral: `Glob` (enumerate), `Read` (active files), `Write` (new archives), `Edit` (active files), `Grep` (cross-ref scan). ## Handoff with other skills - **`docs-discovery`** — archive files excluded from default topic-loading globs. On-demand read only when relevant historical context suspected. - **`docs-check`** — when surfacing `Status: FIXED` for an entry being closed, may note "this entry will be archive-eligible at next `docs-archive` invocation". No automatic chaining. - **`adr-author`** — ADR files (`docs/adr/NNNN-*.md`) are NOT processed by this skill. ADRs use a different lifecycle (per-decision separate files, no rotation).