article-enrichment

What this skill does

# 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

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`).