article-enrichment — From Raw Dumps to Useful Brain Pages

Convention: see conventions/quality.md for citation rules, verbatim-quote requirements, and back-link enforcement.

Convention: see _brain-filing-rules.md for filing rules. Article pages live under media/articles/ for raw ingest; personalized one-of-one synthesis output uses the sanctioned media/articles/<slug>-personalized.md exception.

What this does

Takes an article brain page that's a wall of raw extracted text and rewrites it as a structured page with:

• Executive Summary — 2-3 sentences, the ONE thing worth remembering
• Why It Matters — connects to the user's specific projects + interests (read from brain context, not assumed)
• Quotable Lines — 3-5 VERBATIM quotes worth referencing in essays
• Key Insights — actual insights, not topic labels
• Surprising or Counterintuitive — what makes this content unique
• See Also — standard markdown links to related brain pages

Raw source content is preserved in a collapsed <details> section so the original is never lost.

When to invoke

• New article page lands in the brain via media-ingest with needs_enrichment: true
• Existing article page is a wall of text under a ## Content header with no synthesis
• User says a brain page is useless, boring, or a dump
• An LLM-judge brain-quality eval fails on quotability or actionability for an article page

The pipeline

1. READ      → Open the article brain page; parse frontmatter + body.
2. SCAN      → Look for ## Content (raw dump) and absence of ## Executive Summary.
3. CONTEXT   → gbrain query the article's key entities to ground "Why It Matters".
4. ENRICH    → Sonnet (default) or Opus (for high-value content) restructures.
5. WRITE     → Replace ## Content with the structured sections; preserve raw
               source in <details>; clear needs_enrichment in frontmatter.
6. CROSS-LINK→ Add back-links from referenced people/companies pages
               (Iron Law per conventions/quality.md).

Invocation

The skill itself is markdown instructions to the agent. It does NOT ship a deterministic CLI command in v0.25.1. The agent uses gbrain's existing operations:

# 1. Find candidate pages
gbrain query "needs_enrichment: true type:article" --limit 50

# 2. For each candidate, read the page
gbrain get media/articles/<slug>

# 3. Enrich via the agent's LLM (Sonnet by default; Opus for high-value)
#    The agent reads the raw content + brain context + writes the structured page.

# 4. Write the enriched page
#    Use the put_page operation with the new structured markdown body.

# 5. Cross-link entities
#    For every person/company mentioned, add a timeline back-link.

Quality bar

An enriched page passes if it has:

• ✅ ## Executive Summary (2-3 sentences)
• ✅ ## Quotable Lines with ≥3 verbatim quotes (literal quotes, not paraphrase)
• ✅ ## Key Insights with ≥3 bullets (insights, not topic labels)
• ✅ ## Why It Matters connecting to specific brain context (not generic)
• ✅ ## See Also with standard markdown links (NOT [[wiki-links]])
• ✅ <details> block preserving the raw source content

Model selection

Rule: for bulk enrichment, do a Sonnet draft pass and spot-check 5 with the LLM-judge brain-quality eval. If quotes are paraphrased, switch to Opus for that batch.

Link convention

All cross-references use standard markdown links: [Title](relative/path.md). NEVER use [[wiki-links]] — they don't render on GitHub.

When it fails

Follow the agent operator protocol for any gbrain error code, exit code, [AGENT] block or notice block. Specific to this skill:

• get_page returns page_not_found: the raw dump moved or the slug is wrong; search for the title before reporting the article missing.
• The rewrite returns revision_conflict: someone else edited the page since you read it. Re-read, re-apply the enrichment to the new text, and save with the new revision; never overwrite blind.
• write_pending (exit 10): poll gbrain write-request <request_id>; only report the page enriched once the receipt commits.

Anti-Patterns

• ❌ Paraphrasing quotes ("the author argues that…"). Quotes are verbatim or they're not quotes.
• ❌ Generic "Why It Matters" ("this is important because innovation"). Tie to specific brain context or remove the section.
• ❌ Inventing topic labels and calling them insights. An insight is a thing the article says that you didn't already know.
• ❌ Discarding the raw source. Always wrap it in <details>.
• ❌ Re-enriching non-idempotently — check the needs_enrichment flag in frontmatter; skip if already false.

Related skills

• skills/media-ingest/SKILL.md — creates the raw article pages this skill enriches
• skills/idea-ingest/SKILL.md — link/article ingestion with author people-page enforcement
• skills/conventions/quality.md — citation + back-link rules

Contract

This skill guarantees:

• Routing matches the canonical triggers in the frontmatter.
• Output written under the directories listed in writes_to: (when applicable).
• Conventions referenced (quality.md, brain-first.md, _brain-filing-rules.md) are followed.
• Privacy contract preserved: no real names, no fork-specific filesystem path literals, no upstream-fork references.

The full behavior contract is documented in the body sections above; this section exists for the conformance test.

Output Format

The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (test/skills-conformance.test.ts).