---
name: build-review
description: Graduate a find item to a full review for unique.rzen.dev. Reads src/content/find/<slug>.mdx, expands the body into a full review, writes src/content/reviews/<slug>.mdx, and links the two via fromFind / promotedTo. Use when the user runs /build-review <slug>, says "review this find", or "graduate <slug>".
disable-model-invocation: true
---

# build-review

Convert one captured `find` into a full `review`. Both records persist — the find stays put as the historical capture, the review becomes the canonical long-form treatment, and the two link to each other.

Invoke from inside the `unique.rzen.dev` repo with a find slug as the argument.

## Inputs

- `src/content/find/<slug>.mdx` — the source find (must exist; abort otherwise).
- `src/content/reviews/<slug>.mdx` — must NOT exist (abort if a review with the same slug is already there; ask the user to disambiguate).

## Procedure

### 1. Read the find

Parse frontmatter. Note: `name`, `subtitle`, `link`, `linkText`, `source`, `topics`, `tags`, plus the body.

If `promotedTo` is already set, abort: "This find has already been promoted to <slug>."

### 2. Suggest a hero asset

Look at the external link and propose a hero asset — a screenshot, demo gif, or product photo from the maker's site.

- Mac apps: an App Store screenshot or hero image from the developer's site.
- Physical products: the maker's product photo.
- Travel destinations: a Wikipedia or Wikimedia Commons photo (free-to-use only).

Tell the user what you'd download and where to place it (`src/assets/reviews/<slug>/hero.<ext>` or similar). Pause for approval before downloading.

### 3. Expand the body

Take the find's 2-3 sentence body and expand it to a full review:

- Lead with a `>` blockquote summary (1-2 sentences) — this renders as the accent-bordered lead per the existing review style.
- 3-5 paragraphs covering: what it is, the specific problem it solves, the concrete details that make it earn its place, and any honest limitations.
- Reference the hero asset inline if downloaded (`![alt](../../assets/reviews/<slug>/hero.png)`).
- Don't pad. If the find body is already complete, the review is just it + a blockquote summary + maybe one paragraph on context.
- Match the voice of existing reviews under `src/content/reviews/` — informative, concise, no sales tone.

### 4. Write the review

File: `src/content/reviews/<slug>.mdx`.

Frontmatter:

```yaml
---
name: "<from the find>"
subtitle: "<from the find — required for reviews>"
date: YYYY-MM-DD             # today (the review date), not the find's date
category: <pick from existing categories or propose a new one>
tags: <merge the find's tags with any review-specific additions>
link: "<from the find>"
linkText: "<from the find, if set>"
description: "<short meta description>"
source: "<from the find>"
fromFind: "<find slug>"
---
```

If the find had no `subtitle`, generate one — it's required on reviews.

### 5. Update the find

Edit `src/content/find/<slug>.mdx` frontmatter: add `promotedTo: <review-slug>`.

(Slug usually matches the find's slug, so `promotedTo` and the find's filename match.)

### 6. Register the hero in `src/lib/hero.ts` (REQUIRED if a hero asset exists)

This is the step that has bitten us repeatedly. **The home grid and category cards do NOT auto-discover review hero assets** — they only show a hero if the review's slug is a key in the `heroes` record exported by `src/lib/hero.ts`. Skipping this step ships a review whose grid card is empty.

For a review with a static image hero (`hero.png`, `hero.jpg`, `hero.webp`):

1. Add an `import` line near the top, alphabetically grouped with the other image imports. The variable name is the slug in camelCase. Example for slug `tablepro`:
   ```ts
   import tablepro from '../content/reviews/tablepro/hero.png';
   ```
2. Add an entry to the `heroes` record, alphabetically by key:
   ```ts
   tablepro: { kind: 'image', src: tablepro },
   ```

For a review with a video hero (`.mp4`), put the import in the second (video) import group and the record entry uses `kind: 'video'`. Match the existing pattern.

If the review legitimately has no hero asset (rare — e.g. text-only reviews like `snewpapers-newspaper-archive`, `sindre-sorhus-older-mac-apps`), explicitly note it in the log entry from step 8 ("no hero asset — text-only review") so the omission is intentional and traceable.

### 7. Verify

- Run `npm run build`. Confirm:
  - `/reviews/<slug>/` exists, shows the source badge and "← First surfaced…" backlink to the find page.
  - `/find/<slug>/` shows the "→ Read the full review" callout pointing to the review.
  - Any bundle that references the find still renders fine; the find card on the grid remains.
  - Visit `/grid/` (or `/`) and confirm the new review's tile renders with its hero — not blank. **If the tile is empty, step 6 was skipped.**

### 8. Update the log

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

```
## YYYY-MM-DD — review: <slug>

Graduated from find captured on <find-date>, source: <source>.
```

## Notes

- The find's slug and the review's slug should match. Same slug = same item across the pipeline; cross-references stay simple.
- Don't move or delete the find. Both records persist. The find is the historical capture; the review is the long-form treatment.
- Never auto-write a review without showing the user the proposed body first. This is editorial work; the skill's job is to draft, not to publish unilaterally.
- If multiple finds describe the same underlying thing, the user should consolidate them manually before running this skill.