article-enrichment

Files (2)

• SKILL.md
• routing-eval.jsonl

SKILL.md (first lines)

# article-enrichment — From Raw Dumps to Useful Brain Pages

> **Convention:** see [conventions/quality.md](../conventions/quality.md) for
> citation rules, verbatim-quote requirements, and back-link enforcement.
>
> **Convention:** see [_brain-filing-rules.md](../_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:

```bash
# 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

| Model | Use when | Quote accuracy |
|-------|----------|----------------|
| **Sonnet** (default) | Bulk enrichment, most articles | Good — occasionally paraphrases |
| **Opus** | High-value content, original-thinking pieces, longreads | Excellent — respects "verbatim" instruction |

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.

## 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

From Ninatuzi/gbrain, MIT.