reports

# Reports Skill ## 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 1. **Save report.** Write to `reports/{category}/{YYYY-MM-DD-HHMM}.md` with frontmatter: ```yaml --- 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} --- ``` 2. **Load latest.** Given a category, find the most recent report file. 3. **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: 1. Compose the report. 2. Scan every link against the failure modes above: - **Brain-page links:** run `git status` in 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. 3. 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. 4. Re-check. 5. 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](../conventions/agent-operator-protocol.md) 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; poll `gbrain 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)