# Spec Sheet — Archivist

**What you are building:** A skill that drains a single intake folder into a fixed archive taxonomy, renames and stamps each item, keeps every index truthful in the same pass, and asks a human whenever a destination is not obvious.

> Bracketed [PLACEHOLDERS] are yours to fill in for your own setup. No credential is needed for this skill, but if you wire it to anything that requires one (a sync step, a remote push), supply that secret via your own secret store — never inline it in the skill file.

## 1. Purpose
Keep an archive findable by filing new arrivals the moment they land, into a small stable set of folders, with the index updated alongside every move. Solve two failure modes at once: an intake that silently becomes a junk drawer, and a taxonomy that sprawls because folders get created on a whim. The skill files what it is sure of, asks about what it is not, and never authors new structure without human sign-off.

## 2. Activation — name and description
Name the skill `[archivist]` (or your own verb-noun like `filer`, `sorter`).

The description is what makes the model auto-trigger, so make it cover both the explicit command and the natural-language asks. Include:
- The slash form: "Use when the user runs `/[archivist]`."
- Natural phrasings: "file the intake", "run the [archivist]", "sort my inbox", "process the archive intake".
- A one-line statement of the job: "File everything in the intake folder into the archive taxonomy, update the index, and ask when a destination is not obvious."
- The mode note: "Interactive by default; with `--headless`, file confident matches and route the rest to `_review`."

## 3. Inputs and preconditions
- Files dropped in `[INTAKE]`: `.md`, `.txt`, `.pdf`, `.docx`, `.pptx`, images.
- Capture-bundle folders in `[INTAKE]`: a folder containing a `summary.md` (which classifies the whole bundle) plus the artifacts it references.
- On interactive runs, items previously parked in `[REVIEW]` are also picked up.
- Precondition: the archive tree and its index/state files already exist (see §5). The skill does not bootstrap the tree.
- Tools to read non-text inputs: a PDF-to-text converter (e.g. `pdftotext`) and `.docx`/`.pptx` text extraction.

## 4. Outputs and side effects
- Each filed item: renamed to a dated convention, given provenance frontmatter (or a sidecar metadata file for binaries), and moved into exactly one taxonomy folder under `[FILED]`.
- The destination folder's own index gains one appended line.
- The root index's "recent" block is rolled to the newest N items / D days, and its per-folder summary lines are refreshed from the folder READMEs.
- A hash log gains the item's content hash.
- A flags log gains one line per item that contains settled-position-grade material.
- Exact duplicates are deleted from the intake (the only deletion the skill performs).
- A final tally is reported.

## 5. Environment and dependencies
Generalize these to your own paths and naming:
- `[ROOT]` — the archive root (e.g. `~/archive`). The skill writes only inside here.
- `[INTAKE] = [ROOT]/intake` — where new arrivals land.
- `[FILED] = [ROOT]/filed` — the taxonomy. Each folder under it has a `README.md` (its filing rule) and an `INDEX.md` (its contents log).
- `[REVIEW] = [ROOT]/_review` — holding pen for items headless could not place.
- `[INDEX] = [ROOT]/INDEX.md` — the root map: a "recent" block plus one summary line per folder, both derived, never hand-authored as source.
- `[HASHES] = [ROOT]/.hashes` — content-hash log for dedupe.
- `[FLAGS] = [ROOT]/FLAGS-FOR-CURATED.md` — append-only log of settled-position material noticed during filing.
- A curated/source-of-truth layer is optional. If present, it lives OUTSIDE `[ROOT]` and the skill must never write to it. If absent, `[FLAGS]` is just a harmless log.
- Text-extraction tooling for PDF/Office formats; image viewing for picture files.
- Typical upstream feeders (optional): a chat-capture skill and a voice-note ingest skill that both write into `[INTAKE]`.

## 6. Procedure
1. List `[INTAKE]`. On an interactive run, also list `[REVIEW]` (a human is now present to resolve what headless could not). If all sources are empty, report and stop.
2. For each item (file or bundle folder):
   a. **Read it, format-aware.** Text files directly; PDFs via the converter; Office files via text extraction; images viewed together with the filename and any sibling `summary.md`. For a bundle, the `summary.md` classifies the whole folder.
   b. **Dedupe.** Hash each file (e.g. sha256). If the hash is already in `[HASHES]`, log "duplicate of <filed path>", remove the intake copy, and continue. This is the only deletion allowed.
   c. **Classify.** Read the top-level folders under `[FILED]` and each one's `README.md`. Choose the single folder whose README the item clearly matches.
   d. **Gate on confidence.** File only on a clear single match. Otherwise — interactive: ask one question offering the plausible folders plus "new folder"; headless: move to `[REVIEW]` with a one-line note.
   e. **No-fit material.** If nothing fits, do NOT silently create a folder. Propose one — a name plus a one-line filing rule — and ask the human to approve, merge into an existing folder, or send to `[REVIEW]`. Create the folder and its `README.md` only on approval.
3. **File it** (these steps are tied — do them together, never partially):
   a. Rename to `YYYY-MM-DD--<source-kind>--<slug>.<ext>`, where `<source-kind>` distinguishes machine-captured from hand-added (e.g. `chat` vs `manual`). Rename a bundle folder the same way; leave its inner files' names alone.
   b. Add frontmatter: `original_name`, `provenance`, `filed_date`, and `source` if known. For binaries, write this as a sidecar metadata file (e.g. `<name>.meta.md`).
   c. Move it — never copy-and-leave.
   d. Append one line to the destination folder's `INDEX.md`. Roll the root index's recent block (keep N items / D days, whichever is smaller — e.g. 10 / 90). Refresh the root's per-folder summary lines from the READMEs.
   e. Append the hash to `[HASHES]`.
4. **Flag rule.** If an item carries settled-position-grade material (a decision, a stated principle, a "we now do X"), append one line to `[FLAGS]` quoting it with its filed path. Take no further action — notice, do not promote.
5. **Depth rule.** If a folder's `INDEX.md` passes ~50 lines, propose a split into two or three sub-folders with filing rules. Create them only on approval, then move the files and rebuild the indexes. Never split without a confirming glance.
6. **Report.** Tally: filed N, asked M, to-review K, duplicates D, flagged F.

## 7. Edge cases and failure handling
- **Empty intake:** report and stop; do nothing else.
- **Ambiguous between two folders:** interactive asks one question; headless routes to `[REVIEW]`. Never coin a destination to dodge the question.
- **Genuinely novel topic:** propose a folder; never auto-create.
- **Duplicate content:** detected by hash; intake copy removed, nothing re-filed.
- **Unreadable / unsupported format:** route to `[REVIEW]` with a note rather than guessing or discarding.
- **Bundle with no `summary.md`:** classify from the contained artifacts and filename; if still unclear, ask (interactive) or `[REVIEW]` (headless).
- **Oversized folder:** depth rule triggers a split proposal, not an automatic reorg.

## 8. Guardrails / hard rules
- **Write only inside `[ROOT]`.** Never touch the curated layer or any path outside `[ROOT]`.
- **Asking is success, not failure.** When unsure, ask; never guess a destination to avoid a question.
- **Indexes stay truthful along the whole path.** The folder line and the recent-block roll happen in the same run as the move — never deferred.
- **Never author taxonomy unattended.** Every new folder and every split passes a human glance; the human approves or adjusts, never the skill alone.
- **Only ever delete exact duplicates.** No other content deletion, ever.
- **Notice, do not promote.** The flag rule logs settled-position material; a separate process owns moving it into the curated layer.

## 9. Acceptance criteria
- Running on a non-empty intake leaves `[INTAKE]` empty except for items explicitly sent to `[REVIEW]` or awaiting a human answer.
- Every filed item is renamed to the dated convention, carries provenance frontmatter (or a sidecar for binaries), and sits in exactly one folder under `[FILED]`.
- The destination folder's `INDEX.md` and the root index's recent block both reflect the new item immediately after the run.
- Re-running on the same input files nothing new and reports them as duplicates (idempotent via `[HASHES]`).
- No new folder or split appears without a recorded human approval.
- An item containing a clear decision or principle produces a line in `[FLAGS]`.
- Nothing outside `[ROOT]` is modified.
- The closing report's counts match what actually happened.

## 10. Adapt to your setup
- Swap in your own `[ROOT]`, and rename `filed/`, `_review/`, `.hashes`, and the flags file to your taste.
- Replace the source-kind tokens (`chat`/`manual`) with whatever provenance distinctions matter to you.
- Define your own top-level folders by writing each one's `README.md` (the filing rule the classifier reads) — the skill discovers folders from these, so the taxonomy lives in the READMEs, not in the skill.
- Tune the recent-block size (N items / D days) and the depth-split threshold (~50 lines) to your volume.
- If you have no curated/source-of-truth layer, keep the flags file as a plain log or drop the flag rule entirely.
- Point your capture/ingest feeders at `[INTAKE]` so arrivals queue for this skill.

```markdown
---
name: archivist
description: >-
  File everything in the intake folder into the archive taxonomy, update the
  index, and ask when a destination is not obvious. Use when the user runs
  /archivist, says "file the intake", or "run the archivist". Interactive by
  default; with --headless, file confident matches and route the rest to
  _review.
---

# Archivist

## Configuration
# ROOT, INTAKE, FILED, REVIEW, INDEX, HASHES, FLAGS — set your paths here.
# Each folder under FILED keeps its own INDEX.md; ROOT/INDEX.md is the map.

## Procedure
# 1. List intake (and _review when interactive). Empty -> report and stop.
# 2. Per item: read format-aware; dedupe by hash; classify against folder
#    READMEs; gate on confidence (file / ask / _review); propose-not-create
#    for novel topics.
# 3. File: rename to dated convention; add provenance frontmatter (sidecar for
#    binaries); move; append folder index line + roll root recent block +
#    refresh folder lines; append hash.
# 4. Flag settled-position material to FLAGS (notice, don't promote).
# 5. Depth rule: oversized index -> propose a split, act only on approval.
# 6. Report the tally.

## Hard rules
# Write only inside ROOT. Asking is success. Keep indexes truthful in the same
# run. Never author taxonomy unattended. Only ever delete exact duplicates.
```