reports

Reports Skill

Contract

This skill guarantees:

• 报告以带时间戳的文件名和 frontmatter 保存
• 关键词路由：查询 → 报告类别映射
• 可通过类别名称加载最新报告
• 报告可通过 gbrain search/query 检索
• 对外发送的报告在交付前须通过可操作性检查（见下文）

Phases

1. Save report. Write to reports/{category}/{YYYY-MM-DD-HHMM}.md with 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}
   ---
   

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

在任何报告送达用户之前（包括晨间简报、会议摘要、研究报告），每个链接都必须回答一个问题：用户能否点击此链接并立即采取行动？ 链接规范（确定性的、绝不猜测的 URL）位于 skills/_output-rules.md 的 Deterministic Links 部分；本检查项补充了交付阶段的失败分类和重试循环。

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 和 Indirect 会阻止交付。Missing 仅为警告——予以标记，但不阻止交付。缺失的链接是诚实的，而间接链接则是失信的承诺。

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

使用方

报告类内容按照 harness 路由约定经由此关卡（这是解析器应用的路由规则，并非机械性保证）：晨间简报（skills/briefing/SKILL.md）、会议摘要、研究报告，以及任何包含外部链接的已保存报告。

出现失败时

对于任何 gbrain 错误 code、退出码、[AGENT] 块或通知块，请遵循智能体操作员协议。针对本技能的具体情况：

• 报告链接未通过交付扫描（失效、死链、间接链接）：交付前先修复；缺失链接只是警告，不会阻止交付。
• 保存报告时返回 write_pending（退出码 10）：在写入提交之前，链接会返回 404；分享前请轮询 gbrain write-request <request_id>。
• 报告查询（gbrain search）结果为空并伴有降级通知：应说明本次搜索仅使用了关键词匹配，而不是说“没有之前的报告”。

反模式

• 保存报告时没有 frontmatter（会导致无法被搜索）
• 不同运行之间使用不一致的分类名称
• 只需要最新报告时却加载全部报告
• 不按关键词路由（强制要求精确的分类名称）
• 交付报告时，用个人资料页、主页或频道链接代替具体内容（间接链接会阻止交付）
• 链接尚未提交并推送的 brain 页面（死链）