rzen
049c6c5377
Disambiguates the one-letter `find` (item) vs `finds` (roundup) split that
kept causing confusion. Audience-facing now: `/bundles/<slug>/`, "Bundle"
labels in home/footer/search.
Internals: `getCollection('finds')` → `('bundles')`, `Entry.type 'finds'`
→ `'bundle'`, `OgFallback 'finds'` → `'bundles'`, `findListMosaic` →
`bundleMosaic`, `FindsPost` → `Bundle`, `findsReferencing` →
`bundlesReferencing`. Build script + generated mosaic dir follow
(`scripts/build-bundle-mosaics.mjs`, `src/generated/bundle-mosaics/`).
Skills `build-finds` → `build-bundle`, `cluster-finds` →
`cluster-bundles`. The `find` collection (individual items) is unchanged.
No URL redirects: low external-link surface area.
115 lines
5.5 KiB
Markdown
115 lines
5.5 KiB
Markdown
---
|
|
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/*.mdx` — the full pool to cluster.
|
|
- `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/<slug>/index.mdx`. 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.
|