158 lines
10 KiB
Markdown
158 lines
10 KiB
Markdown
---
|
|
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).
|