paperclip-distill✓ Pass

SKILL.md Content

---
name: paperclip-distill
description: Use when an operation issue is a Paperclip cursor-window, distill, or backfill. Turn source-bundled Paperclip activity into wiki-insightful project standups, durable project pages, decisions, and history without asset dereferencing.
---

# 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.

License

Declared license: MIT

MIT License

Copyright (c) 2026 paperclipai

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

View the license in the source repository — the version published there is authoritative.