# your blog Filter Reference

## Core Identity

your blog documents "the specific satisfaction found in solving deeply frustrating technical problems."

This means every post must have:
1. **A vex**: Real frustration, time lost, blocked progress
2. **A joy**: Satisfying resolution, understanding gained
3. **Value**: Helps others avoid the same struggle

---

## The Three-Question Test

Apply these questions to every topic candidate. All three must be YES.

### Question 1: Was there genuine frustration?

**YES signals:**
- "I spent 3 hours on this"
- "The error message was useless"
- "The docs said X but reality was Y"
- "It worked locally but failed in CI"
- "I tried 5 different approaches"
- "I almost gave up"

**NO signals:**
- "I wanted to learn about X"
- "This seemed interesting"
- "I read that Y is popular"
- "Someone asked me about Z"

**Examples:**

| Candidate | Frustration? | Verdict |
|-----------|--------------|---------|
| "Hugo hot reload stopped working" | YES - broke workflow | PASS |
| "How to use Hugo partials" | NO - just learning | FAIL |
| "DNS propagation took 48 hours" | YES - delayed launch | PASS |
| "DNS basics explained" | NO - educational | FAIL |

### Question 2: Is there a satisfying resolution?

**YES signals:**
- "Fixed by changing one config line"
- "The root cause was X"
- "Now I understand why it happened"
- "Here's how to prevent this"
- "The solution is elegant"

**NO signals:**
- "Still not sure why it works now"
- "I just kept trying things"
- "The workaround is ugly"
- "I gave up and used a different approach"
- "It's still broken"

**Examples:**

| Candidate | Resolution? | Verdict |
|-----------|-------------|---------|
| "Cache TTL was exactly 168 hours" | YES - root cause found | PASS |
| "Restarting fixed it somehow" | NO - no understanding | FAIL |
| "Env var order matters in shell" | YES - clear insight | PASS |
| "Some race condition I think" | NO - uncertain | FAIL |

### Question 3: Would this help others solve the same struggle?

**YES signals:**
- Problem is common (not unique to your setup)
- Solution is reproducible
- Error message is searchable
- Technology is widely used
- Pattern appears in other contexts

**NO signals:**
- Problem was caused by your typo
- Solution requires your specific infrastructure
- No one else uses this obscure tool
- Problem was already fixed in next version
- Too simple (covered in official docs)

**Examples:**

| Candidate | Helps others? | Verdict |
|-----------|---------------|---------|
| "Cloudflare env vars at build vs runtime" | YES - common confusion | PASS |
| "My server's disk was full" | NO - ops issue, not insight | FAIL |
| "Go 1.22 loop variable change" | YES - affects many codebases | PASS |
| "Typo in my config file" | NO - not transferable | FAIL |

---

## Topic Categories

### GREEN (Strong your blog Fit)

These topic patterns consistently pass the filter:

**Debugging Stories**
- "Why X failed only in Y condition"
- "The bug that appeared after N days"
- "Tracing an error through 5 services"

**Configuration Gotchas**
- "The one setting that breaks everything"
- "Default values that bite you"
- "Config options the docs don't explain"

**Integration Pain**
- "Making A work with B"
- "When version X meets version Y"
- "The hidden dependency you didn't know about"

**Documentation Gaps**
- "What the docs assume you know"
- "The step they forgot to mention"
- "Translating docs into reality"

**Migration Stories**
- "Moving from X to Y: the real challenges"
- "Upgrade paths and their pitfalls"
- "What broke when we upgraded"

### RED (Likely Fails Filter)

These topic patterns usually fail:

**Pure Tutorials**
- "How to install X"
- "Getting started with Y"
- "A beginner's guide to Z"

Why: No frustration, just learning.

**Opinion Pieces**
- "Why I prefer X over Y"
- "The case for Z"
- "My favorite tools"

Why: No specific problem solved.

**News Commentary**
- "New release of X announced"
- "What Y means for the industry"
- "Predictions for Z"

Why: No hands-on experience.

**List Posts**
- "10 tips for better X"
- "5 things to know about Y"
- "Top Z tools for A"

Why: Usually shallow, no narrative.

**Meta Content**
- "How I set up my blog"
- "My writing process"
- "Why I started blogging"

Why: Navel-gazing, not problem-solving.

### YELLOW (Needs Angle)

These can work with the right framing:

**Comparisons** (needs hands-on context)
- BAD: "X vs Y: which is better?"
- GOOD: "I migrated from X to Y and here's what broke"

**Explainers** (needs friction point)
- BAD: "Understanding how X works"
- GOOD: "Understanding why X failed in my case"

**Best Practices** (needs failure story)
- BAD: "Best practices for X"
- GOOD: "The best practice I ignored and regretted"

---

## Filter Application Checklist

For each topic candidate:

```
TOPIC: [title]

1. FRUSTRATION CHECK
   [ ] Real time lost? (not just "I was curious")
   [ ] Multiple attempts? (not first-try success)
   [ ] Blocked progress? (not optional exploration)
   --> Frustration: YES / NO

2. RESOLUTION CHECK
   [ ] Root cause identified? (not "it just started working")
   [ ] Solution understood? (not cargo-culting)
   [ ] Insight gained? (not just workaround)
   --> Resolution: YES / NO

3. VALUE CHECK
   [ ] Common enough? (not unique to your setup)
   [ ] Reproducible? (others can hit this)
   [ ] Searchable? (people will look for this)
   --> Value: YES / NO

FILTER RESULT: [PASS / FAIL / NEEDS ANGLE]
```

---

## Salvaging Failed Topics

When a topic fails the filter, try these transformations:

**Failed: Tutorial-only**
- Find the gotcha: "What mistake does everyone make?"
- Find the edge case: "When does this break?"
- Find the integration: "What conflicts with this?"

**Failed: Opinion-only**
- Add measurement: "I measured X and found Y"
- Add failure: "I tried the opposite and here's what happened"
- Add migration: "I switched and here's what broke"

**Failed: Too broad**
- Narrow to one failure mode
- Focus on one specific scenario
- Pick one moment of frustration

**Failed: No resolution**
- Wait until problem is solved
- Document the investigation as "what I tried"
- Frame as "open question" only if the journey itself has value

---

## Examples: Before and After

### Example 1: Tutorial to Debugging Story

**Before (FAIL):**
```
Topic: "How to use Git submodules"
The Vex: Learning submodules
The Joy: Submodules work now
```

**After (PASS):**
```
Topic: "Git Submodule Breaks Hugo Build with Detached HEAD"
The Vex: Theme updates fail silently, stuck on old version
The Joy: Understanding submodule update workflow
```

### Example 2: Opinion to Experience

**Before (FAIL):**
```
Topic: "Why static sites are better than dynamic"
The Vex: Dynamic sites are slow
The Joy: Static is fast
```

**After (PASS):**
```
Topic: "Migrating from WordPress to Hugo Cut Load Time by 8x"
The Vex: 2.3 second page loads, $40/month hosting
The Joy: 280ms loads, free hosting, understanding why
```

### Example 3: Broad to Specific

**Before (FAIL):**
```
Topic: "Kubernetes networking problems"
The Vex: Networking is hard
The Joy: Understanding networking
```

**After (PASS):**
```
Topic: "Pod DNS Resolution Fails After Node Reboot"
The Vex: Services unreachable, CoreDNS not responding
The Joy: Understanding kubelet restart order
```

# Priority Scoring Reference

## The Priority Matrix

Every topic is scored on three dimensions:

```
Priority Score = Impact x Vex Level x Resolution

Maximum score: 5 x 5 x 5 = 125
Minimum score: 1 x 1 x 1 = 1
```

---

## Dimension 1: Impact

**Question:** How many people face this problem?

### Scoring Rubric

| Score | Description | Examples |
|-------|-------------|----------|
| **5** | Nearly everyone using the technology | "Git merge conflicts", "npm install fails" |
| **4** | Common scenario, many will encounter | "Hugo build fails on CI", "Docker networking issues" |
| **3** | Specific situation, some will encounter | "Hugo theme submodule update", "PaperMod search setup" |
| **2** | Niche scenario, few will encounter | "Hugo with custom CMS integration", "Specific cloud provider quirk" |
| **1** | Rare edge case, almost no one encounters | "Obscure OS + tool combination", "Legacy version issue" |

### Impact Assessment Questions

- Is this technology widely used?
- Is this scenario common in normal usage?
- Would this appear in search results often?
- Have you seen others hit this problem?

### Impact Indicators

**High impact signals (4-5):**
- Multiple Stack Overflow questions about this
- Appears in technology's FAQ or common issues
- You've seen colleagues hit the same problem
- Error message is commonly searched

**Low impact signals (1-2):**
- Can't find others with this issue
- Requires unusual configuration
- Only affects edge case workflows
- Technology is rarely used

---

## Dimension 2: Vex Level

**Question:** How frustrating is the problem?

### Scoring Rubric

| Score | Description | Time Lost | Emotional Response |
|-------|-------------|-----------|-------------------|
| **5** | Major blocker, significant time lost | Hours to days | "I almost quit" |
| **4** | Very frustrating, serious impediment | 2-4 hours | "This is ridiculous" |
| **3** | Annoying but manageable | 1-2 hours | "That was frustrating" |
| **2** | Minor inconvenience | 15-60 minutes | "A bit annoying" |
| **1** | Barely noticeable | < 15 minutes | "Mildly confusing" |

### Vex Level Assessment Questions

- How much time did you lose?
- How many failed attempts before success?
- How unclear was the error message or docs?
- Did this block other work?

### Vex Level Indicators

**High vex signals (4-5):**
- Multiple debugging sessions
- Had to step away and come back
- Involved multiple wrong turns
- Error messages were misleading
- Documentation was wrong or missing

**Low vex signals (1-2):**
- Figured it out quickly
- Error message was helpful
- First Google result had the answer
- Just needed to read the docs more carefully

---

## Dimension 3: Resolution

**Question:** How satisfying is the solution?

### Scoring Rubric

| Score | Description | Understanding Gained | Solution Quality |
|-------|-------------|---------------------|------------------|
| **5** | Elegant fix, deep understanding | "Now I truly get it" | Clean, permanent |
| **4** | Clean solution, good insight | "That makes sense" | Solid, maintainable |
| **3** | Workable fix, some insight | "I see what was wrong" | Functional |
| **2** | Hacky workaround, limited insight | "It works now" | Fragile |
| **1** | Partial fix, still confusing | "Not sure why this works" | Band-aid |

### Resolution Assessment Questions

- Do you understand why the problem happened?
- Is the fix elegant or hacky?
- Could you explain this to others?
- Would you feel confident hitting this again?

### Resolution Indicators

**High resolution signals (4-5):**
- Root cause fully understood
- Fix is simple and elegant
- Learned something transferable
- Can prevent this in the future
- Would feel good sharing this

**Low resolution signals (1-2):**
- Still not 100% sure why it works
- Fix feels fragile
- Couldn't explain to someone else
- Might break again in new context
- Copied the solution without understanding

---

## Score Interpretation

### Score Ranges

| Range | Priority | Action |
|-------|----------|--------|
| **60-125** | HIGH | Write this soon - strong YourBlog material |
| **30-59** | MEDIUM | Good candidate with the right angle |
| **15-29** | LOW | Needs more vex or broader impact |
| **1-14** | SKIP | Not enough value for readers |

### Score Distribution Examples

**HIGH PRIORITY (60+):**
```
"Hugo Build Fails Only on Cloudflare Pages"
Impact: 4 (common CI/CD scenario)
Vex: 4 (hours lost, misleading errors)
Resolution: 4 (version pinning, understanding why)
Score: 4 x 4 x 4 = 64
```

```
"Git Submodule Detached HEAD Breaks Theme Updates"
Impact: 4 (everyone using submodule themes)
Vex: 5 (confusing state, silent failures)
Resolution: 4 (proper update workflow)
Score: 4 x 5 x 4 = 80
```

**MEDIUM PRIORITY (30-59):**
```
"PaperMod Search Feature Setup"
Impact: 3 (PaperMod users wanting search)
Vex: 3 (config not obvious)
Resolution: 4 (clean setup, understanding config)
Score: 3 x 3 x 4 = 36
```

```
"Hugo Partial Caching in Dev Mode"
Impact: 3 (Hugo devs who use partials)
Vex: 4 (confusing behavior)
Resolution: 3 (cache-busting, but feels like workaround)
Score: 3 x 4 x 3 = 36
```

**LOW PRIORITY (15-29):**
```
"Hugo Taxonomy URL Customization"
Impact: 2 (specific SEO need)
Vex: 3 (config spread across files)
Resolution: 3 (works, but verbose)
Score: 2 x 3 x 3 = 18
```

**SKIP (1-14):**
```
"Hugo Server Port Already in Use"
Impact: 3 (common enough)
Vex: 1 (obvious fix: change port)
Resolution: 2 (no insight gained)
Score: 3 x 1 x 2 = 6
```

---

## Tie-Breaking Rules

When topics have equal scores, prefer:

1. **Gap fillers over new topics**
   - Completing existing cross-references builds site coherence
   - Readers may already be looking for this content

2. **Complements recent posts**
   - Related topics create content clusters
   - Readers may follow the thread

3. **Uses covered technologies**
   - Lower research overhead
   - Consistent voice and depth

4. **Clearer narrative structure**
   - Easier to write well
   - Better chance of high-quality result

5. **Stronger vex (if Impact x Resolution tied)**
   - YourBlog identity is about frustration
   - Readers connect with struggle stories

---

## Scoring Calibration

### Common Mistakes

**Over-scoring Impact:**
- "Everyone who uses X" - but how many use X?
- Consider: Is X a mainstream technology?

**Under-scoring Vex:**
- Forgetting how frustrated you were after solving it
- Consider: Would past-you have appreciated this post?

**Over-scoring Resolution:**
- "It works now" != elegant solution
- Consider: Do you truly understand why?

### Calibration Checks

Before finalizing scores, ask:

- **Impact:** Would you share this on HN/Reddit? Would people care?
- **Vex:** Would past-you have been grateful for this post?
- **Resolution:** Could you teach this to a colleague tomorrow?

---

## Quick Reference Card

```
IMPACT (1-5): How many face this?
  5 = Universal    4 = Common    3 = Specific
  2 = Niche        1 = Rare

VEX (1-5): How frustrating?
  5 = Hours/days   4 = 2-4 hours   3 = 1-2 hours
  2 = < 1 hour     1 = < 15 min

RESOLUTION (1-5): How satisfying?
  5 = Elegant      4 = Clean       3 = Workable
  2 = Hacky        1 = Partial

PRIORITY = Impact x Vex x Resolution
  60+  = HIGH      Write soon
  30-59 = MEDIUM   Good with angle
  15-29 = LOW      Needs work
  <15  = SKIP      Not enough value
```

---

## Example Scoring Session

```
TOPIC: "Cloudflare Pages Environment Variables Aren't Available at Build Time"

IMPACT ASSESSMENT:
- Cloudflare Pages is popular for static sites
- Anyone using build-time env vars hits this
- Common enough, but not universal
- Score: 4

VEX ASSESSMENT:
- Error is not obvious (variable just empty)
- Difference between build-time and runtime confusing
- Spent 2 hours figuring this out
- Docs exist but easy to miss
- Score: 3

RESOLUTION ASSESSMENT:
- Understand the runtime vs build-time model now
- Solution is clean (use wrangler.toml or build command)
- Can explain to others confidently
- Not the most elegant (wish it just worked)
- Score: 4

FINAL SCORE: 4 x 3 x 4 = 48 (MEDIUM PRIORITY)

NOTES:
- Good topic but vex could be higher
- Consider framing around the confusion, not just the fix
- Pairs well with other Cloudflare deployment topics
```

# Topic Sources Reference

## Source 1: Problem Mining

Mine topics from real technical struggles. This is the richest source of YourBlog content.

### Where to Look

| Signal Source | How to Access | What to Look For |
|--------------|---------------|------------------|
| Git commit messages | `git log --oneline -50` | "fix:", "workaround:", repeated attempts |
| Shell history | `history \| grep -i error` | Commands run many times, frustrated searches |
| Browser bookmarks | Stack Overflow saves | Problems you needed to reference |
| Slack/Discord | Search your questions | "anyone know why..." messages |
| Meeting notes | Retros, standups | "This took longer than expected" |
| Error logs | Application logs, CI output | Recurring errors, cryptic messages |

### Mining Prompts

Ask the user these questions to surface topics:

**Recent struggles:**
- "What broke in the last week that took more than 30 minutes to fix?"
- "What error message did you see more than twice?"
- "What config change seemed simple but turned into hours of debugging?"

**Recurring frustrations:**
- "What problem keeps coming back?"
- "What do you have to Google every time?"
- "What workaround do you keep using?"

**Near misses:**
- "What almost went wrong but you caught it?"
- "What would have been a disaster if you hadn't noticed X?"
- "What rookie mistake did you almost make (or did make)?"

### Signal Strength

| Signal | Topic Potential | Why |
|--------|-----------------|-----|
| "I spent 4 hours on this" | HIGH | Significant vex, likely deep resolution |
| "The docs were wrong" | HIGH | Common pain, valuable correction |
| "Worked locally, failed in CI" | HIGH | Universal developer experience |
| "Took a few tries" | MEDIUM | Some frustration, may lack depth |
| "That was confusing" | MEDIUM | Depends on transferability |
| "New to me" | LOW | Learning, not struggling |

### Example Mining Session

```
USER INPUT: "I was debugging why my Hugo site wouldn't deploy to Cloudflare"

FOLLOW-UP QUESTIONS:
1. What was the error message?
2. How long did it take to figure out?
3. What did you try first that didn't work?
4. What was the actual fix?
5. Why did it work locally but not in CI?

MINED TOPICS:
- "Hugo Version Mismatch Between Local and Cloudflare Pages"
- "Cloudflare Pages Build Command Silent Failures"
- "Hugo Extended vs Regular: The Binary You Didn't Know You Needed"
```

---

## Source 2: Gap Analysis

Find topics by analyzing what's missing from existing content.

### Gap Types

**1. Explicit "See Also" References**
Posts often mention related topics that don't exist yet.

How to find:
```
Search existing posts for:
- "see also"
- "in a future post"
- "covered elsewhere"
- "for more on this"
- "assuming you know"
```

**2. Prerequisite Assumptions**
Posts assume knowledge that isn't documented.

How to find:
```
Look for:
- "Assuming you have X installed"
- "If you're familiar with Y"
- "This builds on Z"
- Links that 404 or go to external sites
```

**3. Incomplete Series**
"Part 1" posts without follow-ups.

How to find:
```
Look for:
- "Part 1" in titles
- "In the next post"
- "Continued in"
- Numbered series
```

**4. Reader Questions**
Questions in comments, emails, or feedback.

How to find:
```
Look for:
- Comment sections
- Email responses
- Social media replies
- "I tried this but..."
```

### Gap Analysis Process

```
STEP 1: List all existing posts
   content/posts/*.md

STEP 2: For each post, extract:
   - Technologies mentioned
   - "See also" references
   - Prerequisites assumed
   - Follow-up promises

STEP 3: Cross-reference:
   - Which references have no matching post?
   - Which prerequisites are undocumented?
   - Which promises are unfulfilled?

STEP 4: Prioritize gaps:
   - High: Mentioned multiple times
   - Medium: Mentioned once, high traffic post
   - Low: Mentioned once, low traffic post
```

### Example Gap Analysis

```
EXISTING POST: "Setting Up Hugo on Cloudflare Pages"

MENTIONS:
- PaperMod theme (external link, no internal doc)
- Git submodules (assumed knowledge)
- "For custom domains, see [link]" (link to external)

GAPS IDENTIFIED:
1. "PaperMod Theme Customization Without Forking"
   - Referenced but not documented internally
2. "Git Submodules for Hugo Themes: A Sane Workflow"
   - Assumed knowledge, common struggle
3. "Cloudflare Custom Domain Setup: The DNS Gotchas"
   - Referenced external, should be internal
```

---

## Source 3: Technology Expansion

Expand from technologies already covered to adjacent ones.

### Expansion Strategies

**Same Tool, Different Feature**
```
COVERED: Hugo basics
EXPAND TO:
- Hugo partials and caching
- Hugo shortcodes
- Hugo taxonomies
- Hugo modules
- Hugo data files
```

**Same Category, Different Tool**
```
COVERED: Hugo (static site generator)
EXPAND TO:
- Comparing Hugo to Zola
- Migrating from Jekyll to Hugo
- When Hugo isn't enough (Astro, Next.js)
```

**Integration Points**
```
COVERED: Hugo + Cloudflare Pages
EXPAND TO:
- Hugo + Cloudflare Workers
- Hugo + Cloudflare R2 for assets
- Hugo + Cloudflare Analytics
```

**Common Ecosystem Pain**
```
COVERED: Hugo
ECOSYSTEM PAIN:
- Markdown rendering quirks
- TOML vs YAML config
- Theme update management
- Build time optimization
```

### Technology Adjacency Map

For YourBlog's current stack:

```
Hugo
├── Themes
│   ├── PaperMod (current)
│   ├── Theme customization
│   └── Theme switching
├── Deployment
│   ├── Cloudflare Pages (current)
│   ├── GitHub Actions
│   └── Vercel/Netlify alternatives
├── Content
│   ├── Markdown extensions
│   ├── Shortcodes
│   └── Data-driven content
└── Development
    ├── Local preview
    ├── Hot reload
    └── Debug modes
```

### Expansion Validation

Not every adjacent topic passes the YourBlog filter. Validate:

```
EXPANSION CANDIDATE: Hugo shortcodes

FILTER CHECK:
- Frustration potential? YES - Syntax is confusing, errors are cryptic
- Resolution satisfaction? YES - Understanding the template context
- Helps others? YES - Common need, poor docs

VERDICT: VALID EXPANSION
```

```
EXPANSION CANDIDATE: Hugo history (why it was created)

FILTER CHECK:
- Frustration potential? NO - Just interesting information
- Resolution satisfaction? N/A - No problem to solve
- Helps others? NO - Not actionable

VERDICT: INVALID - Too meta, no vex
```

---

## Source Combination

The best topics often come from combining sources:

### Pattern: Problem + Gap

```
PROBLEM: Spent 2 hours debugging theme CSS
GAP: No internal doc on theme customization
COMBINED TOPIC: "PaperMod Theme Overrides: The layouts/ Directory"
```

### Pattern: Problem + Expansion

```
PROBLEM: Hugo build slow on large site
EXPANSION: Build optimization techniques
COMBINED TOPIC: "Hugo Build Time Went from 45s to 3s"
```

### Pattern: Gap + Expansion

```
GAP: Referenced submodules but no doc
EXPANSION: Git tooling in Hugo context
COMBINED TOPIC: "Git Submodules for Hugo: Why They Break and How to Fix"
```

---

## Source Priority by Project Maturity

### New Blog (< 10 posts)

Priority order:
1. **Problem Mining** - Establish identity with real struggles
2. **Tech Expansion** - Fill out the core technology coverage
3. Gap Analysis - Limited gaps to analyze

### Established Blog (10-50 posts)

Priority order:
1. **Gap Analysis** - Fulfill cross-references, complete series
2. **Problem Mining** - Continue adding fresh content
3. Tech Expansion - Strategic growth

### Mature Blog (50+ posts)

Priority order:
1. **Gap Analysis** - Comprehensive coverage, reader questions
2. **Problem Mining** - Keep content current and real
3. **Tech Expansion** - Careful not to dilute focus