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

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 (*_<year>.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: <active-stem>_<year>.md (e.g., LOGGING_ISSUES_2025.md)
   • Header (2 lines): topic + "Archived entries (Status: closed) from <active>. 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 `<active-stem>_2025.md`, `<active-stem>_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_<year>.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).