---
name: docs-archive
description: Rotate entries from active `_ISSUES.md` / `_TODO.md` / `LLM_PROTOCOL_DECISIONS.md` files into **year-month bucket** archive companions (`*_<YYYY>_<MM>.md`). Two rotation criteria: (Rule A) for `_ISSUES.md` / `_TODO.md` — `Status: Closed` entries archive-eligible (Status field per `TOPIC_CODES.md` 3-value vocabulary); (Rule B) for `LLM_PROTOCOL_DECISIONS.md` — **last-15-active rolling window**: entries beyond the 15 most recent rotate by entry-date (LLMP-DEC-67, supersedes the original "annual at ~50" from LLMP-DEC-25). Year-month bucket from the entry's date. Active files retain a header pointer to 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", "archive DEC log") or via LLM-suggest-back when a loaded file is bloated.
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 eligible entries into **year-month bucket** archive companions (`*_<YYYY>_<MM>.md`), keeping the active file as a focused "currently relevant" view. Two rotation criteria: **Status-based** (Rule A) for `_ISSUES.md` / `_TODO.md` per LLMP-DEC-44 vocabulary, and **last-15-active rolling window** (Rule B) for `LLM_PROTOCOL_DECISIONS.md` per LLMP-DEC-67 (supersedes the original yearly-at-~50 rule from LLMP-DEC-25).

## 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-month bucket 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 criteria (two rules)

### Rule A — Status-based (for `_ISSUES.md` / `_TODO.md`)

Move entry X to archive IF `Status: Closed`.

**Year-month** derived from a date in the entry body (e.g., `Status: Closed (2026-04-25)` → bucket `2026_04`; or a `### Resolution` sub-section dated `2026-04-25` → same; or `Superseded by ACCORE-LOG-I-K7M2 (2026-04-25)` → same). If no parseable date in body, default to current year-month. Status vocabulary follows `TOPIC_CODES.md` Status field conventions: only `Closed` is archive-eligible; `Open` and `InProgress` stay active.

**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).

### Rule B — Last-15-active rolling window (for `LLM_PROTOCOL_DECISIONS.md` only)

The Decision Log's entries (`LLMP-DEC-N`) generally do NOT carry `Status` fields — they describe **historical decisions**, not work items with a lifecycle. Status-based archiving doesn't apply.

Instead: **active log keeps last 15 entries** (rolling window — the 15 most-recent `LLMP-DEC-N` IDs). Older entries rotate to archive by **entry date** (year-month bucket from the `Date` column).

Per LLMP-DEC-67 (supersedes the original "annual at ~50 entries" rule from LLMP-DEC-25). Foundational decisions (Rules #1-6, ID format spec, governance, etc.) survive in the **`## Current protocol state (quick reference)` summary** at the top of the active log even after their dated entry archives — that summary is the source of truth for "what's currently active" (LLMP-DEC-25 design + LLMP-DEC-60 governance).

### Why two rules

`_ISSUES.md` / `_TODO.md` track **work items** with a clear lifecycle (Open → InProgress → Closed); the `Closed` filter is meaningful. `LLM_PROTOCOL_DECISIONS.md` tracks **decisions** (each entry is a permanent record of a moment); there's no "Closed" lifecycle. Retention must differ.

## 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-month bucket** present:
   - Filename: `<active-stem>_<YYYY>_<MM>.md` (e.g., `LOGGING_ISSUES_2026_04.md`, `LLM_PROTOCOL_DECISIONS_2026_04.md`).
   - Header: topic + "Archived entries from `<active>` per LLMP-DEC-67 retention policy. IDs preserved (never reassigned). Format identical to active file."
   - Entries: archive-eligible entries dated within that year-month, in original chronological/ID order.
   - **Sparse files OK**: only month-buckets containing at least one archived entry get a file. No empty placeholder files.

2. **Build new active file content**:
   - Original header preserved.
   - **Insert a pointer block immediately after the header**:
     ```
     > **Archived entries**: see `<active-stem>_2026_04.md` (and other year-month buckets as more accumulate).
     > Archive files are not auto-loaded — read on demand if relevant context is suspected (regression hint, supersession reference, ID lookup for archived entry).
     ```
   - 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 (Rule B specifics)

If `LLM_PROTOCOL_DECISIONS.md` is being archived (Rule B):

1. **`## Current protocol state (quick reference)` summary** at top STAYS in the active file unchanged. This summary is foundational — the source of truth for "what's currently active" — and survives all archiving (per LLMP-DEC-25 design + LLMP-DEC-60 governance).
2. **Identify entries beyond the rolling window**: count active table rows under `## YYYY`. If count > 15, the oldest entries (lowest `LLMP-DEC-N` IDs) above the cap are archive-eligible.
3. **Group archive-eligible entries by year-month** based on each entry's `Date` column.
4. **Filename**: `LLM_PROTOCOL_DECISIONS_<YYYY>_<MM>.md` (one file per year-month bucket present in the eligible set; sparse OK).
5. **Pointer block** at top of `## YYYY` section in the active log: brief sentence + reference to all known archive files for this log (e.g., "Earlier entries (LLMP-DEC-1..49) archived to `LLM_PROTOCOL_DECISIONS_2026_04.md` per LLMP-DEC-67"). Update / append as more archives accumulate.
6. **Cross-link integrity**: when active entries reference archived entries by ID (e.g., LLMP-DEC-58 references LLMP-DEC-43), the references remain functional — readers open the archive file. IDs are append-only and stable.
7. **Governance section** in the summary stays synchronized with the LLMP-DEC-67 last-15-active + year-month bucket rule. If the rule itself changes, governance text + this Step 7 + the frontmatter description all update together (cross-LLMP-DEC governance).

Per LLMP-DEC-67 (supersedes the original "annual at ~50 entries" rule from LLMP-DEC-25). Only the new (LLMP-DEC-67) is in effect.

## 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).
