unique/.claude/skills/cluster-bundles/SKILL.md

---
name: cluster-bundles
description: Batch-cluster every existing find item in src/content/find/ into 4-7 thematic bundles. Use when the user wants to bring the find pool up to date all at once — ("re-cluster the finds", "build bundles for everything", "spread the new finds across themed bundles"). For drafting one bundle from a single theme, use build-bundle instead.
disable-model-invocation: true
---

# cluster-bundles

Bulk version of `build-bundle`. Reads the entire `src/content/find/` pool, partitions it into themed clusters, and writes one `src/content/bundles/<date>-<slug>/index.mdx` bundle per cluster. The audience-facing site treats `bundles` as the primary discovery vehicle for individual `find` items, so the goal is *coverage*: by the end of the run, almost every find that deserves a home should have one.

Invoke from inside the `unique.rzen.dev` repo.

## Inputs

- `src/content/find/<year>/<month>/<slug>/index.mdx` — the full pool to cluster (folders are nested by date but slugs are globally unique; iterate with `find src/content/find -name index.mdx`).
- `src/content/bundles/*.mdx` — already-written bundles. Their `items[]` lists are the prior clustering — read these to know which finds already have a home and what themes have been used.
- Optional argument: a number of clusters to target (default: model's call, usually 4-7).
- Optional argument: a list of theme phrases to seed clustering around.

## Procedure

### 1. Read the pool

Read the frontmatter and body of every find. Note the `name`, `subtitle`, `topics`, `tags`, and the body's stated *virtue* (the specific thing that makes the item delightful). Tags and topics are hints, not the answer — the body usually tells you what cluster a find actually belongs to.

Also read every existing bundle's `items[]` array — these are pre-clustered and should not be re-clustered into a new redundant theme. They can still be *re-used* in a new cluster if the new theme genuinely calls for them (see overlap rules).

### 2. Partition into clusters

Aim for 4-7 clusters. Each cluster should:

- Hang off **one specific editorial angle**, phrasable in 4-8 words ("Pocket carry", "The morning kitchen ritual", "Travel as a kind of attention"). Avoid generic buckets ("Tools", "Apps") — those are tag pages.
- Hold **3-8 items**. Below 3 the grid feels thin; above 8 it stops being scannable.
- Be **distinct from existing bundles** in angle, even if a couple of items repeat.

Coverage check: after partitioning, every find should appear in at least one cluster (existing or new). If a find genuinely fits no theme, leave it uncovered and report it — don't pad a cluster with a misfit.

### 3. Overlap rules

Re-use is allowed but rationed. Set a soft budget: at most ~20% of items across all new bundles may be repeats from existing bundles or from other new bundles in this same run. Concretely, for a 25-item pool, that's ~5 reuses total. Track repeats as you draft.

When choosing which items to repeat: only repeat a find when the second theme genuinely illuminates a different facet of it. "It also kind of fits over here" is not enough.

### 4. Confirm with the user

Before writing any files, show a compact plan:

```
Cluster A — "<theme>" (N items)
  - <slug>: <name>
  - ...
Cluster B — "<theme>" (N items)
  ...

Overlap with existing bundles: <slug> appears in <existing-bundle> + <new cluster>; ...
Uncovered finds: <list, or "none">
```

Wait for the user to confirm, refine, swap, or merge clusters. Do not write files until they sign off.

### 5. Write each bundle

Same file format as `build-bundle`. For each cluster, write `src/content/bundles/<YYYY-MM-DD>-<theme-slug>/index.mdx`:

```yaml
---
title: "<Theme phrased as a noun phrase, max ~60 chars>"
date: YYYY-MM-DD
tags: [daily-finds, <topic-tag-1>, <topic-tag-2>]
description: "<One-line meta description.>"
blurb: "<One short editorial sentence; appears in the home feed.>"
items:
  - <slug>
  - <slug>
  - ...
---

> <One audience-facing sentence or two that names what links these finds. Vary the opening — don't reuse 'Today's catch' for every bundle in the run. Read like a magazine standfirst, not a checklist.>
```

Body rules (same as `build-bundle`):

- 1-2 sentence intro paragraph in a blockquote. No headings, no list items, no numbered candidates — the grid handles the items.
- Audience-facing language. Never write "today's pick", "candidates", "winners".
- Vary the opening across the batch. With 4-7 bundles going out the same day, repeating "Today's catch" five times feels mechanical.

### 6. Verify

- Every slug in every `items[]` must exist at `src/content/find/<year>/<month>/<slug>/index.mdx` (locate with `find src/content/find -type d -name "<slug>"`). Confirm before declaring done.
- Run `npm run build`. If any bundle fails to compile, fix and re-run.

### 7. Update the log

Append to `daily-finds.log.md`:

```
## YYYY-MM-DD — cluster run

Wrote <N> bundles from a pool of <M> finds.
Reuses across bundles: <count> (budget: ~20%).
Uncovered finds: <list, or "none">.

Bundles created:
- <date>-<slug-A>: <title> (N items)
- <date>-<slug-B>: <title> (N items)
- ...
```

## Notes

- This skill complements, doesn't replace, `build-bundle`. After a cluster run, `build-bundle` is still the right tool for ad-hoc, single-theme bundles on top of new captures.
- If two themes you're considering have heavy overlap (≥50% same items), they're really one theme — merge them and pick the stronger framing.
- Date all bundles with the run date, not staggered — these are siblings written together, and the home feed will sort them naturally by `title`.
- Don't edit existing bundles when running this. If an existing bundle overlaps with a new cluster you're proposing, either keep the new cluster (overlap-tolerated) or drop it from the plan; do not retroactively rewrite history.