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).

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

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

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.

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.

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).

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

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	—

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.

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.

Reference — Report template

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) |
|---|----------|------|--------------------------------------|

## Đề xuất action
| # | Finding | Action | Lý do |
|---|---------|--------|-------|

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

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.

Reference — References (community — claimed 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

Origin

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

Draft:

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

orca-eval

NPX Install

Tags

SKILL.md Content