@seanyao/roll 0.5.0 → 2.602.2

package/skills/roll-brief/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: roll-brief
+license: MIT
+allowed-tools: "Read, Glob, Grep, Write, Bash(git:*)"
+description: |
+  Owner-facing briefing generator. Summarizes what the agent has done since
+  the last brief: completed US/FIX/REFACTOR, in-progress items, BACKLOG queue
+  status, escalations requiring human attention, and a release-readiness verdict.
+  Three trigger modes: auto on Feature completion, daily morning schedule,
+  or manual $roll-brief invocation. Distinct from roll-.changelog (user-facing
+  changelog) — this is an internal digest for the product owner.
+---
+
+# Roll Brief
+
+> Follows the Architecture Constraints, Development Discipline, and Engineering
+> Common Sense defined in the project AGENTS.md.
+
+Owner-facing digest of autonomous agent activity. Gives the human everything
+needed to decide whether to cut a new release — without having to read every
+commit or diff.
+
+## Distinct from roll-.changelog
+
+| | roll-brief | roll-.changelog |
+|--|-----------|----------------|
+| **Audience** | Product owner (internal) | End users (public) |
+| **Content** | All activity including REFACTOR, escalations, health signals | Only user-visible feature changes |
+| **Trigger** | Feature completion / daily / on-demand | Post-deploy |
+| **Tone** | Operational, candid | Product-facing, polished |
+
+## Trigger Modes
+
+### 1. Feature Completion (auto)
+
+Triggered by `roll-loop` when a set of related Stories under one Feature are
+all marked ✅ Done. The loop passes the Feature name as context.
+
+### 2. Daily Morning (scheduled)
+
+Runs at a fixed time each morning (configurable in `~/.roll/config.yaml`).
+Covers all activity since the previous brief.
+
+```yaml
+# ~/.roll/config.yaml
+brief:
+  daily_time: "08:00"   # local time
+  timezone: "Asia/Shanghai"
+```
+
+### 3. On-Demand
+
+```bash
+$roll-brief                    # since last brief
+$roll-brief --since 2026-05-09 # since specific date
+$roll-brief --feature auth     # scoped to one feature
+```
+
+## Workflow
+
+### Step 1 — Determine Scope
+
+```bash
+# Find timestamp of last brief
+ls .roll/briefs/ | sort | tail -1
+
+# Read .roll/backlog.md — collect all status changes since last brief
+# Read git log — commits since last brief timestamp
+git log --since="{last_brief_timestamp}" --oneline
+```
+
+### Step 2 — Collect Activity
+
+From .roll/backlog.md and git log, classify all items since last brief:
+
+- **Completed**: US-XXX ✅, FIX-XXX ✅, REFACTOR-XXX ✅
+- **In progress**: items currently 🔨
+- **Queue**: items still 📋 Todo (ordered by priority)
+- **Dream findings**: any REFACTOR entries added by roll-.dream since last brief
+- **Escalations**: any ALERT files in `~/.shared/roll/loop/` or `~/.shared/roll/dream/`
+- **Doc coverage**: compute from `guide/en/` and `guide/zh/`:
+  - EN coverage = number of files in `guide/en/`
+  - ZH translation rate = files in `guide/zh/` ÷ files in `guide/en/` × 100%
+
+### Step 3 — Assess Release Readiness
+
+A simple heuristic — not a gate, just a signal for the human:
+
+```
+✅ Release candidate if:
+  - No 🔨 in-progress US items
+  - No open ESCALATE alerts
+  - CI is green (check latest workflow run)
+  - No critical REFACTOR entries flagged in last 48h
+
+⚠️  Hold if any of the above is false
+```
+
+### Step 4 — Write Brief
+
+文件命名：`.roll/briefs/YYYY-MM-DD-{NN}.md`，NN 为当日序号（01 起，零填充两位）。
+计算方式：`ls .roll/briefs/YYYY-MM-DD-*.md 2>/dev/null | wc -l`，+1 即为本次序号。
+
+全部用中文输出。**省略空 section**（无内容时连标题一起不输出）：
+
+```markdown
+# 简报 {YYYY-MM-DD HH:mm}
+
+> 触发：{触发原因} | 覆盖：{起止时间范围}
+
+## 已完成（{N} 项）
+| 编号 | 描述 | 类型 |
+|----|-------------|------|
+| US-XXX | {标题} | 用户故事 |
+| FIX-XXX | {标题} | 缺陷修复 |
+| REFACTOR-XXX | {标题} | 重构 |
+
+<!-- 仅当有 🔨 条目时输出 -->
+## 进行中
+| 编号 | 描述 |
+|----|-------------|
+| US-XXX | {标题} — 开始于 {date} |
+
+<!-- 仅当有 📋 条目时输出 -->
+## 待处理队列（{N} 项）
+| 编号 | 描述 | 优先级 |
+|----|-------------|----------|
+| US-XXX | {标题} | 高 |
+
+<!-- US-AGENT-010: per-agent hit-rate summary (one line). Read the last
+     window_cycles records of runs.jsonl, group by `agent`, format as
+     `agents: pi 8/22 (36%) · deepseek 5/8 (63%)`. Sample < 5 → `(n/a)`.
+     Omit when no records have an agent field (legacy data). -->
+## Agent 路由命中率
+{agents: <name> built/total (pct%) · …}  ← from `runs.jsonl` last 50 cycles
+
+<!-- 仅当 roll-.dream 有新发现时输出 -->
+## 悟见
+{来自 .roll/dream/ 的摘要}
+
+<!-- 仅当有 ESCALATE 告警时输出 -->
+## 需人工介入
+{告警内容}
+
+<!-- 始终输出 doc coverage 数字；若无缺口写"覆盖完整" -->
+## 文档覆盖度
+- guide/en: {N} 个文档
+- ZH 翻译率：{M}/{N}（{%}）
+- {缺口列表 或 "覆盖完整，无缺口。"}
+
+## 发版就绪
+{✅ 可发版 / ⚠️ 暂缓 — 原因}
+
+**下一版本：** `v{YYYY}.{MMDD}.{序号}`
+
+- {本轮新增 1}
+- {本轮新增 2}
+
+---
+*状态：进行中 {N} · 待处理 {N} · 告警 {N} | 下次简报：{datetime}*
+```
+
+**首份简报或传入 `--full-history`**：在"已完成"表格后追加历史汇总区块：
+
+```markdown
+### 历史汇总
+**Epic: {Name}** — {done}/{total} ✅
+```
+
+### Step 4.5 — Commit Brief
+
+写完文件后立即提交，让简报进入 git 历史，便于后续追溯与跨会话审计：
+
+```bash
+git add .roll/briefs/YYYY-MM-DD-NN.md
+git commit -m "docs: roll-brief YYYY-MM-DD-NN — {触发原因}"
+git push origin main
+```
+
+- 触发原因来自调用上下文（Feature 完成 / 每日 / 手动 / `--feature` / `--since`），用一句话填入
+- 写文件失败时不要执行 commit；保持工作区干净，由调用方处理重试
+- 仅 `.roll/briefs/` 下新文件入 commit，不要顺带带入其他无关变更
+
+### Step 5 — Notify
+
+写完文件后在终端或 CI 日志中打印简报路径：
+
+```
+📋 $(msg brief.generated ".roll/briefs/YYYY-MM-DD-NN.md")
+   $(msg brief.release_readiness): ✅ $(msg brief.release_ready_status)
+```
+
+有升级事项时须显著打印，不得遗漏。
+
+## Scheduler Configuration
+
+roll-brief runs **locally**, triggered either by roll-loop (on Feature
+completion) or by local cron (daily morning). The agent reads local
+BACKLOG state and git history directly.
+
+### Local cron (daily morning)
+
+Installed automatically via `roll loop on` alongside roll-loop and roll-.dream.
+The cron entry is generated using the configured agent — no manual cron editing needed.
+
+### Triggered by roll-loop
+
+When roll-loop detects a Feature is fully complete, it invokes roll-brief
+automatically — no separate cron entry needed for that trigger.