Techcle Wiki

SKILL

6 min read

Article Outline Skill

Generate a structured outline for the next article in The Long Run series, commit it to the planning workspace, and open a PR for board review.

When to use

  • When assigned a Paperclip task to outline an article
  • When the Managing Editor asks you to start work on a specific article number
  • When generating the planning document for an upcoming article

Procedure

Step 1 — Identify the target article

  1. Read repos/thelongrun-publishing/docs/content-strategy.md — find the article roadmap table and identify the article to outline:

    • Look at the distribution schedule (repos/thelongrun-publishing/docs/distribution-schedule.md) for the next publish date
    • Identify which article number has no completed outline yet (no substantial content in repos/thelongrun-publishing/docs/articles/NNN/article.md)
    • If a Paperclip task specifies an article number, use that

  2. Confirm the article number (NNN) and title from the roadmap table.

Step 2 — Read context documents

Read all of these before writing a single line of outline:

  1. repos/thelongrun-publishing/docs/editorial.md — tone, voice, structure principles, guardrails
  2. repos/thelongrun-publishing/docs/content-strategy.md — series arc, phase context, article roadmap, writing style guidelines
  3. The preceding article in repos/thelongrun-publishing/src/content/articles/ (or repos/thelongrun-publishing/docs/articles/) — understand what the prior piece established and how to avoid repeating it
  4. Any notes in repos/thelongrun-publishing/docs/articles/NNN/ if the folder already exists — incorporate existing notes

Step 3 — Draft the outline

Write a detailed outline in repos/thelongrun-publishing/docs/articles/NNN/article.md. The folder is the planning workspace; this is NOT the final article.

Outline structure (see references/outline-template.md for the full template):

# Article NNN: [Full title from content-strategy.md]
 
**Key Message:** [One sentence — the central tension or insight the article must land]
 
**Series:** [Phase letter] — [Phase name] (Part X of Y)
**Publish Date:** [Date from distribution schedule]
 
---
 
## Story Outline
 
### Opening: [Name the opening move]
[3–5 bullet points describing what the opening must do:
 - What shared reality or experience it starts from
 - What the initial tension is
 - What question it opens without resolving]
 
### The shift / What we're observing
[3–5 bullet points:
 - What has changed or is changing
 - How to name it precisely without over-claiming
 - What concrete evidence or scenario illustrates it]
 
### Evidence and examples
[3–6 bullet points of specific, grounded examples:
 - Use realistic scenarios matching the reader's role (architect, senior dev, EM)
 - Name specific technologies/contexts when it serves the point
 - Do NOT use fictional statistics — use observed patterns instead]
 
### Implications and tensions
[3–5 bullet points:
 - What this complicates, breaks, or requires rethinking
 - Trade-offs to hold, not resolve
 - Questions that should remain open]
 
### Close
[2–3 bullet points:
 - How to end without resolving everything
 - What question or observation leaves the reader thinking
 - Do NOT provide a solution or prescription]
 
---
 
## Series connections
 
[Table or bullet list of related articles and how this one connects — what it builds on, what it
must NOT repeat, and how it differentiates itself. Check articles 001–012 for overlapping themes.]
 
## Notes and potential examples
 
[Open scratchpad: angles to develop, examples to research, questions to explore]

Step 4 — Apply editorial guardrails

Before committing, review the outline against these checks (from repos/thelongrun-publishing/docs/editorial.md and repos/thelongrun-publishing/docs/content-strategy.md):

Voice:

  • Opens from shared reality, not future claims
  • No “we need to…” or prescriptive framing
  • Tension held, not resolved
  • Phase C tone if article 012+: drops reader into discomfort directly

Structure:

  • Essay arc, not listicle arc
  • No bold lead-sentence pattern in section descriptions
  • Transitional tissue between sections is noted

Differentiation:

  • Checked preceding 2–3 articles for overlap
  • Key insight is distinct from prior articles
  • Bainbridge / 012 territory not re-entered unless explicitly building on it

Examples:

  • Concrete and grounded, not hypothetical generalisations
  • Role matches work type (architect ≠ junior dev)
  • Timings realistic (AI research 20–30 min, not hours)

Step 5 — Create or update the checklist

If repos/thelongrun-publishing/docs/articles/NNN/checklist.md does not exist, create it:

# Article NNN checklist
 
## Status
 
- [ ] Outline drafted
- [ ] Outline reviewed (Managing Editor)
- [ ] Draft written
- [ ] Draft reviewed (Managing Editor)
- [ ] Social posts written
- [ ] Social posts reviewed
- [ ] Images generated
- [ ] Published
 
## Schedule
 
- Outline PR: [today's date]
- Publish date: [from repos/thelongrun-publishing/docs/distribution-schedule.md]

If it already exists, update the “Outline drafted” line with today’s date.

Step 6 — Commit and push

  1. Stage only the files you created/modified under repos/thelongrun-publishing/docs/articles/NNN/:

    git add repos/thelongrun-publishing/docs/articles/NNN/article.md repos/thelongrun-publishing/docs/articles/NNN/checklist.md

  2. Commit with a clear message:

    docs: add outline for article NNN — [short title]

Co-Authored-By: Paperclip <noreply@paperclip.ing>

  3. Push the branch:

    git push origin feature/article-NNN-[slug]

Step 7 — Open a PR

Open a GitHub PR using gh pr create:

Title: "Article NNN outline: [title]"

Body:
## What this is

Outline for Article NNN of The Long Run series.

- **Article:** [Number and title]
- **Series phase:** [Phase letter and name]
- **Planned publish date:** [date]
- **Key message:** [one sentence]

## Outline summary

[2–3 sentences describing the arc: opening move, central tension, how it closes]

## Reviewer checklist

- [ ] Key message is distinct from prior articles
- [ ] Opening works without prior series context
- [ ] Tension is genuine (not resolved prematurely)
- [ ] Examples are concrete and grounded
- [ ] Phase-appropriate tone

## Related

- Paperclip task: [TEC-XX identifier]
- Series article list: [repos/thelongrun-publishing/docs/content-strategy.md](../repos/thelongrun-publishing/docs/content-strategy.md)

Step 8 — Update Paperclip

After opening the PR, update the Paperclip issue:

  1. Set status to in_review
  2. Post a comment with:
    • Link to the PR
    • One-sentence summary of the outline’s key message
    • Any open questions or editorial decisions the board should weigh in on

Failure modes to avoid

MistakeWhy it matters
Writing prose instead of an outlineThe outline is for the board to review and redirect — prose at this stage wastes revision cycles
Opening with future-tense claimsViolates the “start from current reality” principle
Reusing examples from prior articlesReaders follow the series; repetition reads as padding
Prescribing solutionsPhase C explores tensions, not fixes
Skipping the series-connections sectionThe Managing Editor needs to verify differentiation before approving
Setting status: published in frontmatterPublishing is handled by a separate GitHub Action; use status: draft

Notes

  • The repos/thelongrun-publishing/docs/articles/NNN/ folder is the planning workspace. It holds outlines, notes, and social drafts.
  • The repos/thelongrun-publishing/src/content/articles/NNN-slug.md file is the Astro content file — only created when the article is ready to stage for review.
  • Never create the Astro content file during the outline phase.

Graph View