138 lines
6.8 KiB
Markdown
138 lines
6.8 KiB
Markdown
---
|
|
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).
|