spine-framework

What this skill does

# SPINE Framework

Substance first, polish last. Every great article needs a strong spine.

## Important: SPINE is for Evaluation, Not Structure

**NEVER:** Use SPINE acronym as headings in articles (e.g., "S — Stakes", "P — Point")

**ALWAYS:** Use information-carrying headings that describe actual content (e.g., "Why Your JWT Implementation Is Vulnerable", "The Retrieval Bias Problem")

SPINE evaluates whether articles have these elements—it doesn't dictate article structure. Headings must be relevant to content, not framework labels.

## The Hierarchy

When in conflict, prioritize in this order:

| Priority | Element | Core Question |
|----------|---------|---------------|
| 1 | **Point** | What's the non-obvious insight? |
| 2 | **Stakes** | Why should anyone care? |
| 3 | **Illustration** | Does the proof actually prove? |
| 4 | **Nuance** | What could go wrong? |
| 5 | **Exit** | Did you land the plane? |
| 6 | **Voice** | Authority without arrogance? |
| 7 | **Clean** | Mechanical polish? |

**Iron Law:** No insight = no article. Point comes before everything.

---

## S — Stakes (Reader Contract)

An article without clear stakes is a lecture no one asked for.

### The First 30 Seconds

- MUST: Make WHO this is for explicit in first 5-10 lines
- MUST: State concrete, felt problem (not abstract)
- MUST: Define what reader will DO (not just understand)
- MUST: Set scope boundaries ("This covers X, not Y")
- SHOULD: Name assumed knowledge ("Assumes familiarity with X")

### Litmus Tests

- Could a reader decide in 20 seconds if this is for them?
- Is the problem something they've *already experienced* (not hypothetical)?
- Would they feel stupid if they shared this and it wasn't relevant to the recipient?

### Bad vs Good

| Bad | Good |
|-----|------|
| "Let's explore balanced retrieval." | "You'll learn a retrieval pattern that prevents confirmation bias in RAG systems." |
| "Authentication is important." | "Your JWT implementation probably has one of these three vulnerabilities." |
| "This post is about caching." | "By the end, you'll know when Redis makes things slower, not faster." |

---

## P — Point (Core Insight)

A grammatically perfect article with no insight is still a 4/10.

### Requirements

- MUST: State core insight in ONE sentence without "how"
- MUST: Challenge a default belief or common practice
- MUST: Place insight in first 20% of article
- MUST: Repeat insight at least twice (intro + conclusion)
- SHOULD: Name a pattern readers feel but haven't articulated

### Insight Categories

| Type | Example |
|------|---------|
| Challenges belief | "Microservices make most systems slower to develop, not faster" |
| Exposes mistake | "Your 'secure' password hashing is probably using the wrong work factor" |
| Names the pattern | "Retrieval isn't neutral—query framing creates epistemic bias" |
| Reveals mechanism | "Why code review catches bugs but not bad design" |

### Litmus Tests

- Would a senior engineer want to read more after just the thesis sentence?
- Does the insight make someone uncomfortable or defensive? (Good sign)
- Could this insight be a tweet that gets mass engagement?

---

## I — Illustration (Proof That Proves)

Abstract correctness isn't enough. Show it working.

### Accuracy & Proof Requirements

- MUST: All claims backed by running code OR verified trusted web sources
- MUST: Code examples actually run and produce shown output
- MUST: External sources cited with URLs (no "some say" or "experts believe")
- MUST: Remove claims you cannot prove with code or trusted sources
- MUST: Statistics must be from verified sources with citations
- NEVER: Make up examples, outputs, or claims
- NEVER: Use hypothetical scenarios as proof
- NEVER: Fabricate data or results
- NEVER: Include unverified statistics (no "studies show" without citation)

**Iron Law:** If you can't prove it with running code or a verified source, remove it.

### Examples

- MUST: Include at least one end-to-end example (problem → solution)
- MUST: Show output, not describe it
- MUST: Use realistic data (no `foo/bar`)
- MUST: Tie example directly back to stated problem
- SHOULD: Include comparison (naive approach → failure → improved approach)

### Code Quality

- MUST: Test code before publishing (actually runs)
- MUST: Show output generated by running the code shown (not fabricated)
- MUST: Make code copy-paste friendly (no screenshots, no invisible characters)
- MUST: Show error handling or explicitly mark as elided
- MUST: Show interfaces/types, not just implied
- MUST: Verify all code examples produce claimed results
- SHOULD: Specify dependencies and versions
- SHOULD: Distinguish pseudocode from real code
- NEVER: Use inconsistent naming across sections
- NEVER: Show output that doesn't match actual code execution

### Diagrams & Visuals

- MUST: Reference every diagram in text or provide caption
- MUST: Make diagrams legible at 50% zoom
- MUST: Explain something text alone wouldn't
- NEVER: Use color as only differentiator (accessibility)
- NEVER: Duplicate what prose already says clearly

### Litmus Test

Could a reader implement this after reading, without googling?

---

## N — Nuance (Intellectual Honesty)

Experts trust authors who admit weaknesses. Amateurs hide them.

### Failure Modes

- MUST: Name the failure mode that will bite readers first
- MUST: Discuss at least 2 failure modes total
- MUST: Include "This breaks when..."
- SHOULD: Address false positives/negatives (if applicable)

### Tradeoffs

- MUST: Acknowledge costs (latency, complexity, maintenance, cognitive load)
- MUST: State clearly when NOT to use this
- SHOULD: Mention alternative approaches
- SHOULD: Steelman the opposite position

### Litmus Tests

- Would you mass send this to your former team?
- Did you include the caveat you'd add verbally when presenting?
- If this approach failed for a reader, would they blame you or themselves?

---

## E — Exit (Land the Plane)

Most articles fail here. They trail off instead of concluding.

### Strong Endings

- MUST: Restate the insight, not the content
- MUST: Make clear exactly when to use this pattern
- MUST: Provide crystal-clear one-sentence takeaway
- MUST: Echo the opening promise (callback)
- SHOULD: Extensions/next steps feel additive, not tacked on
- SHOULD: Final paragraph sounds like domain expertise, not a recap
- NEVER: End with "I hope this was helpful!"
- NEVER: End with "There's much more to explore."

### The Callback Test

- MUST: Conclusion echoes the opening promise
- MUST: If you deleted the middle 50%, intro and conclusion would still connect

### Bad vs Good Endings

| Bad | Good |
|-----|------|
| "In conclusion, we covered X, Y, and Z." | "The next time retrieval feels 'off,' check your query framing before your embeddings." |
| "I hope this was helpful!" | "This pattern costs you 40ms. It buys you answers your users actually trust." |
| "There's much more to explore." | "Start with the bias detection query. Most teams find something in the first hour." |

---

## Voice — Authority Without Arrogance

10/10 articles sound confident, not loud.

### Tone

- MUST: Use declarative sentences ("This fails because..." not "It might be problematic...")
- MUST: Make every adjective measurable or remove it
- MUST: Explain WHY it works, not just that it works
- SHOULD: Engage disagreement, not dismiss it
- NEVER: Use marketing fluff ("game-changing", "revolutionary", "powerful", "robust")
- NEVER: Moralize ("developers should...", "you need to...")

### Reader Respect

- MUST: Match depth to stated audience (don't explain imports to senior engineers)
- SHOULD: Define jargon or deliberately gatekeep (both valid—be intentional)
- NEVER: Include "throat clearing" paragraphs (preamble that delays point)
- NEVER: Restate what was just said (unless genuinely reframed)
- NEVER: Use filler transitions ("Now let's take a look at...")

### Litmus Test

Would a senior engineer trust this without knowing who wrote it?