Contract
This skill guarantees:
- Reports saved with timestamped filenames and frontmatter
- Keyword routing: query → report category mapping
- Latest report loadable by category name
- Reports are searchable via gbrain search/query
- Outbound reports pass the Actionability Gate (below) before delivery
Phases
- Save report. Write to
reports/{category}/{YYYY-MM-DD-HHMM}.mdwith frontmatter:--- title: {report title} type: note # a type the default pack declares; `report` is undeclared report_type: {category name} category: {category name} date: {YYYY-MM-DD} time: {HH:MM PT} --- - Load latest. Given a category, find the most recent report file.
- Keyword routing. Map common queries to report categories:
- "email" / "inbox" → ea-inbox-sweep
- "social" / "mentions" → social-mentions
- "briefing" / "morning" → morning-briefing
- "meeting" → meeting-sync
- Custom mappings configurable
Output Format
Saved: reports/{category}/{YYYY-MM-DD-HHMM}.md
Loaded: full report content with metadata.
Actionability Gate
Before any report reaches the user — a morning briefing, a meeting digest, a
research report — every link must answer one question: can the user click
this and immediately act? The link canon (deterministic, never-guessed URLs)
lives in skills/_output-rules.md under Deterministic Links; this gate adds
the delivery-time failure taxonomy and the retry loop.
Four failure modes
| Mode | What it means | Example |
|---|---|---|
| Broken | Link is fake or a placeholder | https://example.com, TODO-find-link |
| Dead | Link to a brain page that isn't committed/pushed | Page written but not pushed — the link 404s |
| Indirect | Link goes somewhere, but not the right place | x.com/alice-example (profile) instead of x.com/alice-example/status/<id> (the specific post) |
| Missing | Actionable item mentioned with no link at all | "the clip making the rounds (~800K views)" with no URL |
Broken, Dead, and Indirect block delivery. Missing is a warning — flag it, don't block. A missing link is honest. An indirect link is a broken promise.
Blocked vs warning
| Pattern | Status | Why it fails |
|---|---|---|
x.com/<handle> |
Blocked | Profile ≠ post. Link to x.com/<handle>/status/<id> |
| Bare publication domain | Blocked | Homepage ≠ article. Add the article path |
youtube.com/@channel |
Blocked | Channel ≠ video. Link to youtube.com/watch?v=... |
| Brain-page link, file uncommitted | Blocked | Link 404s until committed + pushed |
example.com / TODO placeholder |
Blocked | Not a real link |
google.com/search?q=... |
Warning | Search ≠ source. Link to the actual result |
| Actionable bullet with no URL | Warning | Where? Link it or describe how to find it |
The retry loop (agent-run checks)
There is no enforcement script. The agent runs these checks itself before delivering any report with links:
- Compose the report.
- Scan every link against the failure modes above:
- Brain-page links: run
git statusin the brain repo — an uncommitted page behind a link is a Dead link; commit + push first.gbrain get <slug>confirms the page exists at all. - External links: a profile, homepage, or channel URL standing in for specific content is Indirect.
- Brain-page links: run
- If a check fails, fix the link:
- Have the direct URL (post ID, article path, filing page)? Use it.
- Don't have it? Search the source for the specific item.
- Can't find it? Remove the link and describe the content instead: "clip on @alice-example's timeline, ~800K views — search there." Never leave a profile link as a substitute for a content link.
- Re-check.
- Max 2 retries → deliver with an explicit warning flag if Missing-class warnings remain. Broken, Dead, and Indirect links never ship.
LLM-prompt gate snippet
Paste into any report-generating prompt (subagent digests, research summaries, cron report jobs):
ACTIONABILITY GATE: Before finishing, verify every link answers "can the user
click this and act immediately?"
- Every X link → https://x.com/{user}/status/{post_id} — NEVER a profile link
- Every article → full URL with path — NEVER a bare domain
- Every brain-page link → committed + pushed, or don't link it
- If you don't have the direct URL → describe the content WITHOUT a link
- A missing link is better than an indirect link
Consumers
Report surfaces route through this gate by harness-routing convention (a
routing rule the resolver applies, not a mechanical guarantee): morning
briefings (skills/briefing/SKILL.md), meeting digests, research reports,
and any saved report that carries external links.
When it fails
Follow the agent operator protocol for any gbrain error code, exit code, [AGENT] block or notice block. Specific to this skill:
- A report link fails the delivery scan (broken, dead, indirect): fix it before delivery; a missing link is a warning, not a blocker.
- Saving the report returns
write_pending(exit 10): the link 404s until the write commits; pollgbrain write-request <request_id>before sharing it. - A report lookup (
gbrain search) is empty with a degraded notice: say the search was keyword-only rather than "no prior report".
Anti-Patterns
- Saving reports without frontmatter (makes them unsearchable)
- Using inconsistent category names across runs
- Loading all reports when only the latest is needed
- Not routing by keyword (forcing exact category name)
- Delivering a report with a profile/homepage/channel link standing in for specific content (Indirect links block delivery)
- Linking a brain page that hasn't been committed and pushed (Dead link)