---
name: create-site-doc
description: Brainstorm a new blog site — propose authors and categories, then write a design doc to /docs
argument-hint: <site_name> <slug> "<description>"
---

# Create Site Doc

Help the user brainstorm the starting documentation for a new blog site. Output lands in `/Users/jturman/development/john/docs/{slug}.md`.

**Arguments:** $ARGUMENTS

Parse as:
- `site_name` — human-readable title (e.g. `"My Blog"`). May be quoted.
- `slug` — URL-safe slug (e.g. `my-blog`)
- `description` — remaining text (may be quoted), short summary of what the site is for

If any of these are missing, ask the user before proceeding.

---

## Step 1 — Propose authors (interactive)

Generate **about 10** author personas that collectively cover the site's subject matter from distinct angles — different expertise, voice, background, and audience. Avoid overlap; aim for a team where each voice brings something the others can't.

For each author produce:

- **Name** — a plausible human name, 1–3 words, title-cased. Not generic ("The Writer", "Blogger Bob").
- **Description** — 2–4 sentences that **must start with "You are a ..."**. Establish who they are, what they know deeply, their voice/perspective, and who they write for.

Present the full list to the user as a numbered markdown list:

```
1. **Name**
   You are a ...
```

Explicitly invite the user to edit, add, remove, swap, or re-roll any author. **Loop on feedback** — revise and re-present until the user confirms the list is good.

Do not proceed to Step 2 until the author list is confirmed.

---

## Step 2 — Propose categories (interactive)

Using the site name, description, and the **confirmed** author list, propose **6 or 7 categories** that:

- Span the site's topical range (every confirmed author should have at least one category they could write into)
- Read like natural browsing buckets a reader would click (not named after authors, not internal jargon)
- Don't overlap heavily with each other

Present as a bulleted list with a one-line rationale per category:

```
- **Category Name** — one-line rationale
```

Invite edits, additions, removals, renames. **Loop on feedback** until the user confirms.

Do not proceed to Step 3 until the category list is confirmed.

---

## Step 3 — Write the doc

Target path: `/Users/jturman/development/john/docs/{slug}.md`

If the file already exists, show its current contents to the user and confirm overwrite before writing.

Write the file with exactly this structure:

```markdown
# {Site Name}

**Slug:** {slug}

## Description

{description}

## Authors

### {Author Name}

{You are a ... description}

(repeat for each confirmed author, separated by blank lines)

## Categories

- **{Category}** — {one-line rationale}
(repeat for each confirmed category)
```

---

## Step 4 — Report

Print the final file path and a one-line summary: `{N} authors, {M} categories written to docs/{slug}.md`.