Paperclip Distill

---
name: paperclip-distill
description: Use when an operation issue is a Paperclip cursor-window, distill, or backfill — `operationType: "distill"` or `"backfill"` and the body references a Paperclip source bundle for a project or root issue. Turn raw Paperclip activity into a wiki-insightful project page, decisions log, and history note. This skill exists specifically to replace the stiff, datestamp-heavy templated output that the deterministic distiller produces.
---

# Paperclip Distill

Distill Paperclip project, issue, comment, and document activity into durable wiki pages. The success criterion is **wiki-insightful, not procedural**: a reader who has never seen Paperclip should learn what the project is, what was decided, what is at risk, and what the current state is — without scanning a list of `## [YYYY-MM-DD]` headers.

## When this skill is needed

- Cursor-window distillation: the routine fed you a bounded source bundle of recent Paperclip activity for one project or root issue.
- Backfill: the user asked to seed the wiki with the historical activity of a project or root issue. Source window may be wide.
- Manual `distill-paperclip-now` request from the UI.

If the operation issue is `operationType: "ingest"` (raw file) or `operationType: "query"`, this is the wrong skill — use `wiki-ingest` or `wiki-query`.

## Destination space

In Phase 1, every Paperclip distill, backfill, and cursor-window operation writes into the
default wiki space. The operation issue should always carry `spaceSlug: "default"`. If an
operation issue passes any other slug, stop and surface the mismatch in a comment — do not
write Paperclip-derived pages into a non-default space.

This rule is destination-only. The Paperclip source scope (which projects, root issues,
comments, documents are read) is set elsewhere in the operation issue and is independent of
the destination.

## Inputs

- A Paperclip source bundle (issue list, comment refs, document refs, source hash, cursor window).
- An existing or planned `wiki/projects/<slug>/standup.md` page path.
- An existing or planned `wiki/projects/<slug>/index.md` page path.
- The operation issue's target `wikiId`, `spaceSlug`, space root, and the target space's `AGENTS.md` for page conventions.
- The current `wiki/projects/<slug>/standup.md`, `wiki/projects/<slug>/index.md`, `decisions.md`, and `history.md` if they already exist (so you write a *patch*, not a rewrite).

## Paperclip Asset Gate

Do not treat Paperclip assets/attachments or issue work products as source text for this skill.

- Allowed Paperclip body text: issue descriptions, comment bodies, document bodies.
- Assets/attachments are metadata-only until a separate approved extraction policy exists.
- Work products are metadata-only until a separate approved extraction policy exists.
- Never fetch `/api/assets/:id/content`.
- Never dereference a work-product `url`, preview URL, artifact URL, or other linked destination from this skill.
- If an operator asks for attachment/work-product content distillation, stop and point them at the Phase 5 asset/work-product security gate policy instead of improvising.

## Anti-patterns to avoid

The deterministic templating this skill replaces produced these failure modes — do not reproduce them:

1. **Datestamp-as-section-header.** Lines like `## [2026-04-15] paperclip-distill | proposed` belong in `wiki/log.md`, not in the project page. The project page is durable knowledge; the log is the audit trail.
2. **Procedural status lists.** `Issue mix: 3 todo, 5 in_progress, 2 done` tells the reader nothing they could not read off Paperclip directly. State *what is happening and why it matters*, then cite the issues that constitute the evidence.
3. **One-line-per-issue dumps.** A page that is mostly `- PAP-1234: title (in_progress, updated 2026-...)` is an issue list, not a wiki page. Group issues by what they are *about* (a decision, a risk, a workstream) and cite multiple issues per bullet when they share a story.
4. **Mechanical "Current as of" timestamps everywhere.** One `current_as_of` in frontmatter is enough.
5. **No interpretation.** "Active issues: PAP-A, PAP-B, PAP-C" is bookkeeping. "The team is concentrating on the schema migration ([PAP-A], [PAP-B]) and has parked the index work pending capacity ([PAP-C])." is wiki-insightful.
6. **Opaque identifiers in prose.** UUIDs, cursor ids, source hashes, run ids, and raw metadata belong in logs or frontmatter when needed, not in executive-facing project narrative.

## Workflow

1. **Read the bundle in full.** Don't sample. Read every issue title, every comment, every document key the bundle includes. Note: which issues are decisions, which are risks/blockers, which are recently completed, which are inflight.
2. **Read the existing project page** (if any) so you write a patch, not a rewrite. The "Decisions" section in particular accumulates over time — never wipe accepted decisions; supersede them with `> ⚠ reversed by ...` callouts when something later overrides them.
3. **Read the target space's `AGENTS.md`** for page conventions: filename style, YAML frontmatter shape, link style, voice. Always pass the operation issue's `wikiId` and `spaceSlug` to LLM Wiki tools.
4. **Write `wiki/projects/<slug>/standup.md` first.** Every Paperclip project represented in the wiki must have this file. It is the executive standup: where the project stands today, what changed recently, what is blocked or risky, and what happens next. Use stable sections, in this order:
   - Frontmatter (`type: project-standup`, `project: <slug>`, `current_as_of: YYYY-MM-DD`, `sources`).
   - **Executive Readout** — one short paragraph that explains the current project posture in plain language.
   - **What Changed** — the meaningful work completed or advanced since the last window. Group by concept; cite issues/comments/documents only as evidence.
   - **Decisions** — accepted/rejected/reversed decisions that changed the project direction. Omit when none exist.
   - **Blockers / Risks** — current blockers and risks with named owner or next action when the source provides one.
   - **Next Actions** — concrete next actions and owners inferred from Paperclip issues, not vague aspirations.
   - **Links** — durable wiki project page and relevant Paperclip project/issues/documents.
   Rewrite the standup to today's state. Do not append endless dated sections; the audit trail belongs in `wiki/log.md` and Paperclip comments.
5. **Write `wiki/projects/<slug>/index.md`** with these stable sections, in this order:
   - Frontmatter (`type: project`, `current_as_of: YYYY-MM-DD`, `tags`, `sources`).
   - **Overview** — 2–4 sentences saying what the project is and why it exists. Use the project description if it exists; otherwise synthesise it from the root issue.
   - **Current Direction** — narrative paragraph naming the active workstreams, the immediate next concrete deliverable, and the stance on risks. Cite 2–4 issues, do not list 20.
   - **Workstreams** — a short, grouped list. Each line is a workstream or idea, not an issue.
   - **Decisions** — accepted and reversed decisions with one paragraph each. Each decision cites the issue / approval / comment that ratified it. Format: `### Decision — short title` then a paragraph; never a bare bullet list.
   - **Open Risks / Blockers** — what could derail the project, with the issue ref that surfaces it. Skip this section when the bundle has no risk signal — do not pad with `_(none)_`.
   - **References** — readable links to the current standup and supporting Paperclip tasks/documents. Keep hashes and cursor ids out of the narrative.
6. **Optionally write `wiki/projects/<slug>/decisions.md`** when the project has accumulated more decisions than the project page can carry without becoming a wall of text. Each decision is a `## ` section with: short title, accepted/reversed/superseded status, one-paragraph rationale, citing the source. *Do not* duplicate decisions already on the project page — link instead.
7. **Optionally write `wiki/projects/<slug>/history.md`** for a compact narrative timeline of meaningful project changes. **Not** an issue dump — group by phase ("Discovery", "Architecture", "Build", "Stabilisation"), not by date. Each phase is a paragraph that cites the 2–4 issues that defined it.
8. **Refresh `wiki/index.md`** under the `## Projects` section — one line per durable project page with a one-sentence summary of the project's purpose, plus a link to the current `wiki/projects/<slug>/standup.md` when present.
9. **Append `wiki/log.md`** entry — this is where the datestamp belongs:
   ```
   ## [YYYY-MM-DD] paperclip-distill | <project name>
   - standup: wiki/projects/<slug>/standup.md
   - page: wiki/projects/<slug>/index.md
   - source hash: `<hash>`
   - cursor window: <start> → <end>
   - notes: <one line on what changed in this distill, e.g. "decisions section grew with PAP-X reversal", "low-signal window, no page changes">
   ```
10. **Surface bundle warnings** (clipped sources, low signal, stale hash). Bundle warnings → `human_review_required: true` on the patch. Do not paper over them.

## Voice

- Past-tense for completed work, present-tense for current state, future-tense only with citation ("the team plans to … per [[…]]").
- Cite Paperclip source refs inline using their issue identifier (e.g. `PAP-3179`), not opaque UUIDs.
- Use issue links as evidence, not as the shape of the page. Headings and paragraphs should be organized by concepts, workstreams, decisions, and blockers.
- Wiki voice: terse, factual, neutral. No "the team is excited to" or "this initiative aims to".
- Headings are about *content*, not metadata. `## Schema migration` not `## Active Issues`.

## When the bundle has no signal

If the bundle has no durable signal — no decisions, no risk, no completed work, only routine status churn — do **not** write a project page. Instead:

- Append a `paperclip-distill | low-signal skip` log entry naming the cursor window.
- Close the operation issue with a one-line "no durable change in this window" comment.
- Do not bump the source hash on a binding that has no proposed page.

## Verification

Before closing the operation issue:

- [ ] The project page reads as wiki content, not as a Paperclip status report. A reader new to the company should understand what the project is.
- [ ] `wiki/projects/<slug>/standup.md` exists for the represented project and reads as an executive current-state update, not a raw issue dump.
- [ ] Decisions section names decisions, not issues — every decision has a one-paragraph rationale and a citation.
- [ ] The page contains exactly one `current_as_of` (in frontmatter), zero `## [YYYY-MM-DD]` headings (those go to the log).
- [ ] Bundle warnings (clipped, low signal, stale hash) are surfaced; the patch carries `human_review_required: true` when the deployment is authenticated/public.
- [ ] `wiki/index.md` and `wiki/log.md` are updated.
- [ ] No file under `raw/` was modified.

## Tools

`wiki_search`, `wiki_read_page`, `wiki_write_page`, `wiki_list_sources`, `wiki_read_source`. Always include the operation issue's `wikiId` and `spaceSlug`. The Paperclip source bundle arrives as part of the operation context — you do not need to assemble it.