orca-eval

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: orca-eval

WHAT

Purpose và context

目的与上下文

Purpose: Vòng tự cải thiện quy trình: đọc lại session logs → rút best practice / anti-pattern → report md → đề xuất hành động (promote thành skill, sửa CLAUDE.md, thêm hook…). Report là đề xuất — mọi action phải qua
```
propose
```
→ gate, không tự thực hiện.
Trigger (when to use):
- ```
/orca-eval [N]
```
  — N = số session gần nhất cần quét (vd 5/10/15)
- Không có N → chỉ quét session hiện tại
- User nói "đánh giá session", "rút best practice", "tối ưu quy trình từ lịch sử"
Non-goals: không tự thực hiện action (promote skill, sửa CLAUDE.md, thêm hook); không sửa/xoá session log; không auto-trigger mỗi 30 session (Phase 2, chưa nằm trong skill này).

目的： 工作流自我改进循环：重新读取 session 日志 → 提炼最佳实践/反模式 → 生成 Markdown 报告 → 提出改进 action（提升为 skill、修改 CLAUDE.md、添加 hook……）。报告仅是建议——所有 action 都必须经过
```
propose
```
→ gate，不得自动执行。
触发条件（何时使用）：
- ```
/orca-eval [N]
```
  ——N = 需要扫描的最近 session 数量（例如 5/10/15）
- 未提供 N → 仅扫描当前 session
- 用户提出“评估 session”“提炼最佳实践”“从历史记录优化流程”
非目标： 不自动执行 action（提升 skill、修改 CLAUDE.md、添加 hook）；不修改或删除 session 日志；不每 30 个 session 自动触发（属于 Phase 2，尚未包含在此 skill 中）。

Mental model

心智模型

*.jsonl session logs → orca-eval-scan.sh digest (prompts · tool errors · lệnh lặp) → 4 tín hiệu (Correction · Repetition · Friction · Win) → finding → đúng 1 action (promote-to-skill · update-CLAUDE.md · add-hook · keep · ignore) → report draft → DỪNG chờ duyệt

*.jsonl session 日志 → orca-eval-scan.sh digest（prompts · tool errors · 重复命令）→ 4 类信号（Correction · Repetition · Friction · Win）→ finding → 恰好对应 1 个 action（promote-to-skill · update-CLAUDE.md · add-hook · keep · ignore）→ 报告草稿 → 停止并等待批准

。

Input và output contract

输入与输出约定

	Field	Required?	Ý nghĩa
In	`N`	không	số session gần nhất theo mtime `*.jsonl` ; default = session hiện tại
In	session logs `~/.claude/projects/<project-slug>/*.jsonl`	có	chỉ đọc
Out	`llmwiki/wiki/draft/orca/DDMMYY-eval-report.md`	có	theo Report template
Out	`wiki/index.md` + `wiki/log.md` cập nhật	có	—
Out	bảng action hiển thị cho user	có	"xong" = user đã thấy bảng; action chưa thực thi

	字段	必需？	含义
输入	`N`	否	按 mtime 选取最近 N 个 session；默认 = 当前 session
输入	session 日志 `~/.claude/projects/<project-slug>/*.jsonl`	是	只读
输出	`llmwiki/wiki/draft/orca/DDMMYY-eval-report.md`	是	按照报告模板生成
输出	更新 `wiki/index.md` + `wiki/log.md`	是	—
输出	展示给用户的 action 表	是	“完成”表示用户已看到该表；action 尚未执行

Rules và capabilities

规则与能力

RULE-01 (MUST): Read-only với session logs — không sửa/xóa
```
*.jsonl
```
.
RULE-02 (MUST): KHÔNG nạp nguyên transcript — 1 session có thể hàng trăm KB; đọc qua digest của scanner.
RULE-03 (MUST): Mỗi finding gắn đúng 1 action; action chỉ thực hiện sau khi user duyệt (qua
```
propose
```
nếu là thay đổi code/skill).
RULE-04 (MUST): Format JSONL của Claude Code không có spec công khai — scanner fail thì fallback session hiện tại và báo rõ, không sinh report rỗng.
Capabilities: đọc session log cục bộ qua scanner; ghi draft wiki + index + log. Không mạng, không sửa code/config.

RULE-01 (MUST)：对 session 日志只读——不得修改或删除
```
*.jsonl
```
。
RULE-02 (MUST)：不得加载完整 transcript——单个 session 可能达到数百 KB；应通过 scanner 的 digest 读取。
RULE-03 (MUST)：每个 finding 必须恰好对应 1 个 action；只有在用户批准后才能执行 action（涉及 code/skill 变更时需通过
```
propose
```
）。
RULE-04 (MUST)：Claude Code 的 JSONL 格式没有公开规范——scanner 失败时应回退到当前 session 并明确报告，不得生成空报告。
能力：通过 scanner 读取本地 session 日志；写入 draft wiki、index 和 log。不联网，不修改 code/config。

Failure boundaries

失败边界

Scanner fail → partial: fallback session hiện tại, báo rõ; không sinh report rỗng.
Không có tín hiệu nào → report ghi rõ 0 finding (không bịa finding).
User chưa duyệt → action ở trạng thái proposed, skill dừng.

Scanner 失败 → 部分结果：回退到当前 session 并明确说明；不得生成空报告。
未发现任何信号 → 报告必须明确记录 0 个 finding（不得虚构 finding）。
用户尚未批准 → action 保持 proposed 状态，skill 停止执行。

HOW

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	`N`	Scan: `skills/orca-eval/assets/orca-eval-scan.sh [N]` từ repo root	digest	fail → B01
W02	judgment	digest	Distill 4 loại tín hiệu	danh sách finding + bằng chứng	—
W03	effect	finding	Report theo template + cập nhật index/log	draft report	—
W04	judgment	finding	Action proposal: bảng action cho user, DỪNG	bảng action	không duyệt → dừng

Chi tiết từng bước (nguồn chân lý cho W01–W04):

Scan — chạy
```
skills/orca-eval/assets/orca-eval-scan.sh [N]
```
từ repo root. Script trả về digest gọn (user prompts, tool errors, lệnh Bash lặp lại). KHÔNG nạp nguyên transcript — 1 session có thể hàng trăm KB.
Distill — từ digest, tìm 4 loại tín hiệu:
- Correction: user sửa lời agent ("không, dùng X", "sai rồi", "actually…") → quy tắc ứng xử mới
- Repetition: chuỗi lệnh/thao tác lặp ≥ 3 lần qua các session → ứng viên skill-hóa
- Friction: tool error lặp lại, permission prompt nhiều lần, retry loop → ứng viên hook/permission/config
- Win: workflow user approve nhanh, không phải sửa → ghi nhận best practice giữ nguyên

Report — ghi

llmwiki/wiki/draft/orca/DDMMYY-eval-report.md

theo template dưới. Cập nhật

wiki/index.md

wiki/log.md

Action proposal — mỗi finding gắn đúng 1 action:
```
promote-to-skill
```
/
```
update-CLAUDE.md
```
/
```
add-hook
```
/
```
keep
```
/
```
ignore
```
. Hiển thị bảng action cho user. DỪNG — action chỉ thực hiện sau khi user duyệt (qua
```
propose
```
nếu là thay đổi code/skill).

步骤	类型	输入	操作	输出/退出	失败/下一步
W01	确定性	`N`	从 repo root 扫描： `skills/orca-eval/assets/orca-eval-scan.sh [N]`	digest	失败 → B01
W02	判断	digest	提炼 4 类信号	finding 列表 + 证据	—
W03	副作用	finding	按模板生成报告并更新 index/log	报告草稿	—
W04	判断	finding	提出 action：向用户展示 action 表，停止	action 表	未批准 → 停止

各步骤详情（W01–W04 的唯一事实来源）：

扫描——从 repo root 运行
```
skills/orca-eval/assets/orca-eval-scan.sh [N]
```
。脚本返回精简 digest（user prompts、tool errors、重复的 Bash 命令）。不得加载完整 transcript——单个 session 可能达到数百 KB。
提炼——从 digest 中查找 4 类信号：
- Correction：用户纠正 agent（“不，用 X”“错了”“其实……”）→ 新的处理规则
- Repetition：相同命令或操作在多个 session 中重复 ≥ 3 次 → skill 化候选
- Friction：重复出现 tool error、频繁出现 permission prompt、retry loop → hook/permission/config 候选
- Win：用户快速批准工作流且无需修正 → 记录并保留该最佳实践

报告——按照下方模板写入

llmwiki/wiki/draft/orca/DDMMYY-eval-report.md

。更新

wiki/index.md

wiki/log.md

。

Action 建议——每个 finding 恰好对应 1 个 action：
```
promote-to-skill
```
/
```
update-CLAUDE.md
```
/
```
add-hook
```
/
```
keep
```
/
```
ignore
```
。向用户展示 action 表。停止——只有在用户批准后才能执行 action（涉及 code/skill 变更时需通过
```
propose
```
）。

Input

输入

Tham số	Ý nghĩa	Default
`N`	Số session gần nhất (theo mtime của `*.jsonl` )	session hiện tại

Session logs nằm tại

~/.claude/projects/<project-slug>/*.jsonl

— slug là cwd với

thay bằng

(vd

-Users-giatran-orca-workspaces-setup-evaluation

参数	含义	默认值
`N`	按 `*.jsonl` 的 mtime 选取最近 N 个 session	当前 session

Session 日志位于

~/.claude/projects/<project-slug>/*.jsonl

——slug 为将

替换为

后的 cwd（例如

-Users-giatran-orca-workspaces-setup-evaluation

）。

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	recovery	scanner fail (format JSONL đổi)	fallback session hiện tại, báo rõ trong report	không có gì để quét → báo, không sinh report rỗng	W02
B02	conditional_required	action là thay đổi code/skill và user duyệt	chuyển qua `propose` → gate	user không duyệt → dừng	—

ID	类型	条件	行为	跳过/失败	汇合
B01	恢复	scanner 失败（JSONL 格式发生变化）	回退到当前 session，并在报告中明确说明	无可扫描内容 → 报告情况，不生成空报告	W02
B02	条件必需	action 涉及 code/skill 变更且用户已批准	转入 `propose` → gate	用户未批准 → 停止	—

Validation và stopping

验证与停止条件

Scanner là tất định; phân loại tín hiệu là judgment — mỗi finding phải có bằng chứng (session + trích dẫn ngắn) trong bảng. Dừng cứng ở W04 chờ user duyệt.

Scanner 是确定性的；信号分类属于 judgment——每个 finding 都必须在表中提供证据（session + 简短引用）。在 W04 处硬性停止，等待用户批准。

Examples

示例

Positive:
```
/orca-eval 10
```
→ scan 10
```
*.jsonl
```
mới nhất → phát hiện user 4 lần sửa "dùng ./scratchpad/ không /private/tmp" (Correction) → finding gắn
```
update-CLAUDE.md
```
; report
```
llmwiki/wiki/draft/orca/DDMMYY-eval-report.md
```
+ bảng action, DỪNG.
Boundary/failure:
```
orca-eval-scan.sh
```
lỗi vì đổi format JSONL → fallback session hiện tại, report ghi rõ scanner fail; không có tín hiệu nào → báo 0 finding, không sinh report rỗng.

正向示例：
```
/orca-eval 10
```
→ 扫描最新的 10 个
```
*.jsonl
```
→ 发现用户曾 4 次纠正“使用 ./scratchpad/ 而不是 /private/tmp”（Correction）→ finding 对应
```
update-CLAUDE.md
```
；生成报告
```
llmwiki/wiki/draft/orca/DDMMYY-eval-report.md
```
和 action 表，然后停止。
边界/失败示例：
```
orca-eval-scan.sh
```
因 JSONL 格式变化而失败 → 回退到当前 session，报告明确记录 scanner 失败；未发现任何信号 → 报告 0 个 finding，不生成空报告。

Reference — Report template

参考——报告模板

markdown

---
type: draft
title: "DDMMYY-eval-report"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

markdown

---
type: draft
title: "DDMMYY-eval-report"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

DDMMYY-eval-report

Type: draft Status: proposed Tags: orca-eval, eval-report Proposed: YYYY-MM-DD Scope: <N session / session hiện tại> — <danh sách file jsonl đã quét>

Best practices

#	Tín hiệu	Loại	Bằng chứng (session, trích dẫn ngắn)

#	Tín hiệu	Loại	Bằng chứng (session, trích dẫn ngắn)

Đề xuất action

#	Finding	Action	Lý do

#	Finding	Action	Lý do

Origin

Sessions: <paths đã quét>
Generated by: /orca-eval

undefined

Sessions: <paths đã quét>
Generated by: /orca-eval

undefined

Reference — Giới hạn

参考——限制

Read-only với session logs — không sửa/xóa
```
*.jsonl
```
.
Format JSONL của Claude Code không có spec công khai — scanner fail thì fallback session hiện tại và báo rõ, không sinh report rỗng.
Auto-trigger mỗi 30 session: Phase 2 (cần Stop-hook + counter), chưa nằm trong skill này.

对 session 日志只读——不得修改或删除
```
*.jsonl
```
。
Claude Code 的 JSONL 格式没有公开规范——scanner 失败时应回退到当前 session 并明确报告，不得生成空报告。
每 30 个 session 自动触发：Phase 2（需要 Stop-hook + counter），尚未包含在此 skill 中。

Reference — References (community — claimed 2026-06-11)

参考——社区参考资料（标注日期为 2026-06-11）

Repo	Áp dụng được gì
BayramAnnakov/claude-reflect	Regex bắt correction ("no, use X", "remember:"), queue → review 2 giai đoạn, routing global vs project CLAUDE.md, `/reflect-skills` tìm pattern lặp để skill-hóa
haddock-development/claude-reflect-system	Stop-hook auto-run cuối session (mẫu cho Phase 2 auto-trigger 30 session), cross-skill best-practice extraction
netresearch/claude-coach-plugin	Friction detection — đếm permission prompts / retry loops làm tín hiệu cải tiến
robonuggets/skills — calibrate	In-session self-improvement: review conversation hiện tại, đề xuất sửa skill/memory có chủ đích
a-c-m reflection.md gist	Bản tối giản 1 file — giữ skill này gọn, không over-engineer

Repo	适用内容
BayramAnnakov/claude-reflect	使用 Regex 捕获 correction（“no, use X”“remember:”），queue → 两阶段 review，按全局与项目 CLAUDE.md 进行 routing，使用 `/reflect-skills` 查找重复模式并进行 skill 化
haddock-development/claude-reflect-system	在 session 结束时通过 Stop-hook 自动运行（Phase 2 每 30 个 session 自动触发的示例），支持跨 skill 提取最佳实践
netresearch/claude-coach-plugin	Friction detection——统计 permission prompts / retry loops，将其作为改进信号
robonuggets/skills — calibrate	Session 内自我改进：review 当前对话，有针对性地提出 skill/memory 修改建议
a-c-m reflection.md gist	单文件精简版——让此 skill 保持简洁，避免过度设计

Origin

来源

Raw:
```
llmwiki/raw/evalution-engineering.md
```

Draft:

wiki/draft/orca/110626-orca-eval-skill.md

Raw：
```
llmwiki/raw/evalution-engineering.md
```

Draft：

wiki/draft/orca/110626-orca-eval-skill.md