Article Draft Workflow

Workflow

agent starticle

Phase 1 — Intake & Analysis

Read the input material. Determine its nature:

Input type	What to extract
Prompt / topic description	Core thesis, target audience, key questions to research
Document / notes	Claims, sources, structure, terminology, unresolved questions
Audio transcript	Definitions, hypotheses, axioms, predictions, observations, and learnings voiced by participants — these are the intellectual spine of the article and must be captured as atoms
Existing article (rewrite)	Current structure, what works, what’s missing

Transcript priority rule: When the input is an audio transcript or conversation log, treat knowledge extraction as the primary task. Scan aggressively for:

Definitions — any time a speaker defines or redefines a term
Hypotheses — any testable claim or prediction about outcomes
Axioms — foundational beliefs stated as non-negotiable truths
Predictions — forward-looking claims about what will happen
Observations — patterns noticed through experience or data
Learnings — confirmed insights, especially where a hypothesis was validated or invalidated

These become {% atom %} tags in the article. They are more valuable than the surrounding prose because they flow into the Knowledge Base aggregate pages and become discoverable across all articles.

Present a brief intake summary:

INTAKE SUMMARY
──────────────────────────────────────────────
Input:        {file name or prompt description}
Topic:        {core subject}
Thesis:       {one sentence — the article's central claim or question}
Audience:     {who this is for}
Atoms found:  {count and types — e.g. "3 hypotheses, 2 definitions, 1 learning"}
Sources:      {count of citable references identified}

Wait for user confirmation before proceeding.

Phase 2 — Structure Plan

Propose an article outline. The outline determines:

Frontmatter — id, title, date, status, tags, domain (if applicable)
Section structure — headings and their purpose
Tag placement plan — where each tag type will appear:

STRUCTURE PLAN
──────────────────────────────────────────────
id:           {kebab-case}
title:        {article title}
date:         {ISO 8601}
tags:         {space-separated}
domain:       {optional}

OUTLINE
  1. Introduction
     - {% tldr %} — {summary sentence}
     - Opening prose
     - {% quote %} — {author, if applicable}

  2. {Section title}
     - Prose with {% cite %} markers
     - {% atom type="definition" %} — {term being defined}
     - {% callout %} — {key insight or implication}

  3. {Section title}
     - {% atom type="hypothesis" %} — {claim}
     - Prose developing the argument
     - {% footnote %} — {caveat or methodology note}

  4. {Section title}
     - {% atom type="learning" %} — {confirmed insight}
     - {% carousel %} — {if comparing alternatives}

  5. Sources
     - {% citation %} entries (×{count})
     - {% bibliography %}

TAG BUDGET
  Atoms:       {count} ({types})
  Citations:   {count}
  Quotes:      {count}
  Callouts:    {count}
  Footnotes:   {count}
  Assets:      {count}
  Carousels:   {count}

Wait for user confirmation or revision before proceeding.

Phase 3 — Research & Enrichment

Before writing, gather the material that will make the article substantive:

Source verification — for every claim attributed to an external source, prepare a {% citation %} entry with key, title, author, date, and URL where available
Atom extraction — formulate each identified insight as a well-crafted atom body. Each atom should:
- Stand alone — readable without surrounding context
- Be typed correctly (definition vs hypothesis vs learning — see atom tag docs)
- Have a date if the insight is time-bound
- Have tags for Knowledge Base filtering
Quote selection — identify 1–3 quotes that anchor the article’s argument in external authority
Gap identification — note any claims that lack sources or areas where the argument is thin

Present a research summary if significant new material was gathered. Otherwise proceed directly to drafting.

Phase 4 — Draft

Write the complete article. Follow these rules:

Document structure

---
type: article
id: {id}
title: {title}
status: draft
date: "{ISO 8601}"
tags:
  - {tag1}
  - {tag2}
domain: {optional}
---

\{% article date="{ISO 8601}" %\}

\{% tldr %\}
{One-sentence summary}
\{% /tldr %\}

## {Section 1}

{prose with \{% cite key="..." /%\} markers}

\{% atom type="{type}" date="{date}" tags="{tags}" %\}
{Knowledge unit — standalone, well-crafted}
\{% /atom %\}

{more prose}

## {Section N}

...

## Sources

\{% citation key="..." title="..." author="..." date="..." url="..." /%\}
{repeat for each source}

\{% bibliography /%\}

\{% /article %\}

Writing principles

Lead with the thesis. The tldr and introduction should make the article’s central claim immediately clear.
Atoms before prose. When a section contains an atom, consider placing it early — it anchors the reader and the Knowledge Base index.
Citations at point of claim. Place \{% cite %\} immediately after the sentence making the claim, not at the end of a paragraph.
Footnotes for tangents. If a thought is interesting but would break the flow, use a footnote.
Callouts for implications. When a finding has a concrete implication (design, business, technical), use a callout to make it scannable.
Quotes as anchors. Use quotes to introduce a section or to lend authority to a controversial claim — not as filler.
Carousels for parallel items. If you’re comparing 3+ alternatives, presenting step-by-step instructions, or showcasing game variants, use a carousel.
One heading level deep. Use ## for sections. Avoid ### except inside carousels or for genuinely subordinate content.

Tag density guidance

Atoms: at least 1 per article, typically 2–5. More is fine if the material is rich.
Citations: 1 per external source. Group all \{% citation %\} entries at the end before \{% bibliography %\}.
Footnotes: 0–5 per article. More suggests the prose needs restructuring.
Callouts: 1–3 per article. More than 4 dilutes their impact.
Quotes: 0–3 per article. One strong opening quote is better than many weak ones.
Carousels: 0–1 per article. Use only when the content genuinely benefits from tabbed presentation.

Present the complete draft to the user. Do not write to disk yet.

Phase 5 — Revise & Write

Incorporate user feedback. Common revision patterns:

Feedback	Action
”Add more sources”	Research and add `\{% citation %\}` + `\{% cite %\}` entries
”This claim needs backing”	Add citation or reframe as hypothesis atom
”Too many callouts”	Merge or remove — keep only the strongest
”Make the atoms stronger”	Rewrite to be standalone and precisely typed
”Add a section about X”	Draft new section following the structure plan
”Change the angle”	Revise thesis, tldr, and atom framing

After the user confirms the draft:

Write to content/articles/{id}/{id}.article.mdoc
If assets are referenced, confirm public/assets/articles/{id}/ exists
Report the file path and a summary of what was written

Do’s and Don’ts

Do:

Wait for explicit user confirmation before writing to disk
Ensure every \{% citation %\} references a real, verifiable source
Use status: draft on first write — the user promotes to published when ready
Use ./ relative format for asset paths (the compiler resolves them to /assets/articles/{id}/)
Lead with the thesis in the tldr and introduction
Place atoms early in a section — they anchor the reader and the Knowledge Base index

Don’t:

Write to disk before explicit user confirmation
Fabricate citations — if a source cannot be verified, note it as unverified in a footnote
Use \{% include %\} — articles are self-contained documents
Skip knowledge extraction from transcripts — definitions, hypotheses, and learnings are more valuable than surrounding prose

Definition of Done

Article file exists at content/articles/{id}/{id}.article.mdoc with valid frontmatter
Root {% article %} tag present with correct date attribute
{% tldr %} present with concise one-sentence summary
Every external claim has a matching {% citation %} and {% cite %} marker
At least one {% atom %} captures a core insight
{% bibliography %} present if any citations exist
Draft was confirmed by user before writing to disk