topic-brainstormer

# Topic Brainstormer

## Overview

This skill generates blog post topic ideas that align with a content identity built around solving frustrating technical problems. It operates through three sequential phases (ASSESS → DECIDE → GENERATE) with **hard quality gates**: every topic must pass a three-question content quality filter before presentation. The output is always a prioritized list with impact/vex/resolution scores, never an unfiltered pile of ideas.

Core principle: **Assess-Decide-Generate with Domain Intelligence**. Gather signals from existing content and problem sources, filter candidates ruthlessly, then score and prioritize the survivors.

---

## Reference Loading Table

| Signal | Load These Files | Why |
|---|---|---|
| filtering topics against blog identity: the three-question test | `content-filter.md` | Loads detailed guidance from `content-filter.md`. |
| scoring topics on impact, vex level, resolution | `priority-scoring.md` | Loads detailed guidance from `priority-scoring.md`. |
| mining topics: problems, gaps, technology expansion | `topic-sources.md` | Loads detailed guidance from `topic-sources.md`. |
| generating angles on one topic or story: six lenses, distinctness, "so what?" gate | `angle-lenses.md` | Loads detailed guidance from `angle-lenses.md`. |

## Instructions

### Phase 1: ASSESS

**Goal**: Gather context about existing content and available topic sources.

**Step 1: Scan existing content**

Read all posts in the content directory. Document:

```markdown
## Content Landscape
Posts found: [N]
Content clusters: [list main themes]
Technologies covered: [list]
Last post date: [date]
```

**Step 2: Identify available sources**

Determine which topic sources have material to mine:
- Problem Mining: Recent debugging sessions, errors, config struggles
- Gap Analysis: Cross-references in existing posts that lead nowhere
- Tech Expansion: Adjacent technologies not yet covered

**Step 3: Note cross-references**

Extract all "see also", "related", and cross-reference mentions from existing posts. Flag any that point to content that does not exist.

**Gate**: Content landscape documented, at least 2 sources identified with material. Proceed only when gate passes.

---

### Phase 2: DECIDE

**Goal**: Generate topic candidates and filter them through the content quality test.

**Quality Filter Rule**: This is non-negotiable. Every candidate must answer YES to all three questions. Unfiltered lists waste user time; apply rigor here.

**Step 1: Mine candidates from identified sources**

Generate 5-10 raw topic candidates from at least 2 sources. For each candidate, capture:
- Source (problem mining, gap analysis, or tech expansion)
- Raw topic area
- Initial vex signal (what frustration exists)

**Step 2: Apply content quality filter to every candidate**

Each topic must answer YES to all three questions:

1. **Was there genuine frustration?** Real time lost, multiple failed attempts, unclear docs, or unexpected behavior that blocked progress.
2. **Is there a satisfying resolution?** Clear fix exists, understanding gained, prevention strategy available, or "a-ha moment" to share.
3. **Would this help others?** Problem is reproducible, not too environment-specific, solution is actionable, frustration is relatable.

**Why this matters**: Topics that fail any question produce weak posts. "How to Set Up Hugo" lacks genuine frustration (official docs already cover installation). "Rewriting a Python CLI in Go Cut Startup Time by 10x" has concrete vex (400ms startup delay) and concrete joy (40ms result).

**Step 3: Reject failing candidates**

Remove any topic that fails the filter. Document why each rejection failed:

| Rejected Topic | Failed Question | Reason |
|----------------|-----------------|--------|
| [topic] | [1, 2, or 3] | [why] |

**Failure Mode Warning — Do Not Generate Tutorial-Only Topics**: "How to Set Up X" with vex listed as "learning a new tool" is not genuine frustration. Find the specific friction point. "Hugo Local Build Works But Cloudflare Deploy Fails" has real vex (version mismatch between local and CI).

**Failure Mode Warning — Do Not Accept Opinion Without Experience**: "Why Go Is Better Than Python for CLI Tools" is debate, not experience. This lacks a specific problem solved, no measurable outcome. Ground in measurement instead.

**Gate**: At least 3 candidates pass the content quality filter. If fewer than 3 pass, return to Step 1 with different sources. Proceed only when gate passes.

---

### Phase 3: GENERATE

**Goal**: Score, prioritize, and present the filtered topic list.

**Step 1: Score each passing topic**

Apply the priority matrix to every candidate:

```
Impact (1-5):     How many people face this problem?
Vex Level (1-5):  How frustrating is the problem?
Resolution (1-5): How satisfying is the solution?

Priority Score = Impact x Vex Level x Resolution

  60-125: HIGH PRIORITY    - Write this soon
  30-59:  MEDIUM PRIORITY  - Good candidate with right angle
  15-29:  LOW PRIORITY     - Needs more vex or broader impact
  1-14:   SKIP             - Not enough value for readers
```

**Why scoring matters**: Unscored lists require user re-evaluation. Always include the priority matrix for every topic.

**Step 2: Write specific titles**

Replace vague category titles with failure-mode titles:
- Bad: "Kubernetes Networking Issues"
- Good: "Pod-to-Pod Traffic Works But Service Discovery Fails"

**Failure Mode Warning — Do Not Use Vague Topic Titles**: "Kubernetes Networking Issues" is too broad to act on. Which issues? What specifically failed? Use failure-mode titles instead: "CoreDNS Returns NXDOMAIN for Internal Services" signals real vex and specificity.

**Step 3: Present prioritized output**

```markdown
## Topic Brainstorm Results

### Source: [problem mining / gap analysis / tech expansion]

### HIGH PRIORITY (Strong vex potential)

1. "[Specific Topic Title]"
   The Vex: [What frustration this addresses]
   The Joy: [What sat