AyCode.Core/.github/skills/docs-archive/SKILL.md

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-65, 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-65 (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-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 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-65 (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-65 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-65"). 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-65 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-65 (supersedes the original "annual at ~50 entries" rule from LLMP-DEC-25). Only the new (LLMP-DEC-65) 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).