# Okr Harness

> Quản lý mục tiêu OKR. Trigger: OKR, mục tiêu, dự án, kế hoạch, tracking, review, dashboard, tiến độ, inbox, capture, retro, bài học.

- Skill: `hoangvantuan/okr-harness` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add hoangvantuan/okr-harness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoangvantuan/okr-harness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: hoangvantuan (https://skillmd.com/u/hoangvantuan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hoangvantuan/okr-harness

---


# OKR Harness: Orchestrator (skill-only)

Entry point quản lý mục tiêu OKR. Đọc state, route, **chạy skill inline**, tổng hợp kết quả.

## Bản đồ skill

| Skill         | Vai trò                                                                            | Ghi          |
| ------------- | ---------------------------------------------------------------------------------- | ------------ |
| `okr-analyze` | Phân tích read-only: metrics, issues, priority, dashboard, trace (xem lại history) | Không        |
| `okr-init`    | Tạo/sửa objective, KR/KI, resources                                                | Có           |
| `okr-plan`    | Tạo/sửa plan, milestones, actions                                                  | Có           |
| `okr-track`   | Track progress, deep review, inbox, closure, sync                                  | Có           |
| `okr-capture` | Ghi nhanh vào inbox                                                                | Có (inbox)   |
| `okr-retro`   | Rút bài học từ phiên, ghi `.okr/lessons/` (record-only)                            | Có (lessons) |
| `okr-shared`  | Quy tắc chung: SOT, schemas, quality gate, delegate, priority                      | Không        |


## Phase 0: Context check

```
if .okr/ không tồn tại:
    → chạy okr-init mode new (inline)
    return
else:
    → Phase 1 (đọc state + xác định intent)
```

## Phase 1: Đọc state + xác định intent

### Preload

Orchestrator tự đọc nhanh (không gọi skill) để xác định state. Đây là **Tier 1 của Preload Contract** (canonical: `okr-shared/references/preload.md`):

```
ls -1 .okr/       → cấp 1, KHÔNG đệ quy: phát hiện context/ + file lẻ/thư mục lạ (cho audit)
objective.md      → frontmatter: type (project/ongoing), status, period
plan.md           → frontmatter: có/không, counters
resources.md      → đọc TOÀN BỘ body (capacity, skills, tool, tài liệu, ngân sách)
actions/          → scan frontmatter: count active, có overdue/blocked?
inbox/            → scan frontmatter: count pending
lessons/index.md  → đọc TOÀN BỘ (bài học, auto-load mỗi phiên)
context/index.md  → conditional: nạp TOÀN BỘ nếu context/ tồn tại (như lessons/index.md)
```

Chỉ frontmatter (trừ `resources.md`, `lessons/index.md`, và `context/index.md` khi tồn tại đọc toàn bộ). Không đọc objective/plan body, action body, log, archive, file detail bài học, hay `context/<slug>.md` body (on-demand, xem contract mục "KHÔNG preload").

Lessons đã nạp → dùng làm **context định hướng** khi skill đề xuất/điều chỉnh trong phiên (đối chiếu area/target liên quan). Quy tắc áp dụng: `okr-shared/references/preload.md` "Áp dụng lessons".
`context/index.md` (nếu nạp) → áp dụng quy tắc `okr-shared/references/preload.md` "Áp dụng context": trước khi skill ghi/đề xuất, quét cột "Khi nào cần đọc", nạp body file khớp. Mọi file mới sinh trong phiên phải reachable theo **bản đồ neo** (canonical: `preload.md` "Reachability khi ghi").

### Intent routing

| State                   | User intent                            | Chạy skill (inline)                   |
| ----------------------- | -------------------------------------- | ------------------------------------- |
| Chưa có .okr/           | Bất kỳ                                 | `okr-init` new                        |
| Có objective, chưa plan | Mặc định                               | `okr-plan` new                        |
| Có objective + plan     | **Mặc định / "hôm nay"**               | `okr-analyze` (dashboard)             |
|                         | "sửa mục tiêu / KR / KI"               | `okr-init` update-objective           |
|                         | "tài nguyên / capacity / skill / tool" | `okr-init` update-resource            |
|                         | "thêm action / sửa plan / sửa action"  | `okr-plan` update                     |
|                         | "track / cập nhật / update"            | `okr-analyze` → `okr-track` light     |
|                         | "review sâu / đánh giá / phân tích"    | `okr-analyze` deep → `okr-track` deep |
|                         | "capture / ghi nhanh / note"           | `okr-capture`                         |
|                         | "inbox / xử lý inbox"                  | `okr-track` inbox-only                |
|                         | "tổng kết / closure / kết thúc"        | `okr-track` closure                   |
|                         | "trace / history / xem lại"            | `okr-analyze` trace                   |
|                         | "rút bài học / tổng kết phiên / retro" | `okr-retro`                           |


**Collision**: state gợi ý khác user intent → ưu tiên user intent + xác nhận lại.

## Phase 2: Thực thi inline

Đọc SKILL.md của skill đích, theo đúng flow của nó. Khi một flow cần chuyển sang skill khác (vd track deep cần áp dụng thay đổi cấu trúc), đọc tiếp SKILL.md kia và thực thi, mang theo context đã có.

### Dashboard (mặc định khi có plan)

Chạy `okr-analyze` (focus=full, max_items=2, horizon_days=3). Render dashboard + nhắc review nếu cần (xem "Nhắc review").

### Track light

1. Chạy `okr-analyze` (focus: progress, overdue, blocked) → thu được analysis.
2. Chạy `okr-track` light, dùng analysis làm input. Tương tác user, cập nhật progress, archive, next action.

### Deep review (chuỗi tuần tự inline, KHÔNG agent team)

1. Chạy `okr-analyze` mode deep: đọc toàn bộ `.okr/` + log history, root cause mỗi issue (≥3 "tại sao?").
2. Chạy `okr-track` deep, mang theo analysis: trình bày root cause → đề xuất điều chỉnh → all-changes confirm. User chọn áp dụng.
3. Ghi progress fields (việc của okr-track).
4. **Áp dụng thay đổi cấu trúc**: với mỗi thay đổi đã confirm thuộc cấu trúc, đọc tiếp `okr-init`/`okr-plan` và thực thi với `pre_confirmed: true` (xem `okr-shared` delegate-protocol). Cùng agent thực hiện, không spawn.
5. Ghi log review.

> Trước đây deep review chạy bằng agent team (analyst + tracker qua SendMessage). Skill-only gộp thành chuỗi tuần tự một agent: phân tích → track → áp dụng. Mất tính song song, đổi lại chạy được ở mọi nền tảng.

### Init / Plan

Chạy `okr-init` (mode new/update-objective/update-resource) hoặc `okr-plan` (new/update). Tương tác user theo flow. Confirm trước ghi.

### Capture

Chạy `okr-capture`: phân loại type, ghi `inbox/YYYY-MM-DD-HHmm-slug.md`. Xem `okr-capture` SKILL.md.

### Inbox / Closure

Chạy `okr-track` với mode tương ứng (inbox-only / closure).

### Trace

Chạy `okr-analyze` mode trace (read-only: xem lại history/archive/log). Xem `okr-analyze/references/flow-trace.md`.

## Phase 3: Tổng hợp

- Gom kết quả các bước.
- Render tóm tắt cho user: thay đổi gì, next step gì.
- Gợi ý rút bài học nếu flow có thực chất (xem `## Rút bài học`).

## Error handling

| Lỗi                       | Xử lý                                                    |
| ------------------------- | -------------------------------------------------------- |
| `.okr/` không tồn tại     | Route `okr-init` new                                     |
| File corrupt              | Báo cụ thể file nào, đề xuất sửa                         |
| Skill flow lỗi giữa chừng | Báo bước nào lỗi, giữ thay đổi đã ghi, hỏi user tiếp     |
| Phân tích thiếu dữ liệu   | Tiếp tục với dữ liệu có, ghi rõ phần thiếu trong báo cáo |


## Nhắc review

Khi hiển thị dashboard, áp quy tắc "Nhắc review" canonical ở `okr-shared/references/metrics.md` (first match, phân Project/Ongoing). Period overdue (Project) là cảnh báo riêng, ưu tiên cao hơn, render block đầu dashboard. KHÔNG định nghĩa ngưỡng riêng ở đây để tránh lệch với analyze/track.

## Test scenarios

### Happy path: Daily check-in

1. User: `/okr-harness`
2. Orchestrator đọc state → có objective + plan + actions active
3. Chạy `okr-analyze` inline → dashboard
4. Render: KR progress, action summary, top 2 priority, review reminder
5. User: "track"
6. Chạy `okr-analyze` (analysis) → `okr-track` light inline
7. Tương tác user, cập nhật, archive, next action
8. Render tóm tắt

### Happy path: Deep review

1. User: "review sâu"
2. Chạy `okr-analyze` deep: root cause mọi issue
3. Chạy `okr-track` deep: trình bày root cause + đề xuất → all-changes confirm
4. User approve → ghi progress fields
5. Có thay đổi cấu trúc → đọc tiếp `okr-init`/`okr-plan` (pre_confirmed) áp dụng inline
6. Ghi log review
7. Render tóm tắt toàn bộ thay đổi

### Error path: Chưa init

1. User: `/okr-harness`
2. `.okr/` không tồn tại
3. Chạy `okr-init` new → hướng dẫn tạo objective + resource

### Error path: Thiếu dữ liệu phân tích

1. `okr-analyze` gặp file thiếu frontmatter
2. Báo cụ thể file/field thiếu
3. Tiếp tục track với phần dữ liệu có, ghi chú phần thiếu trong tóm tắt

## Rút bài học

Thay cho cơ chế tự cải tiến cũ. Việc rút bài học do skill `okr-retro` đảm nhiệm, **user chủ động**.

**Gợi ý cuối flow**: sau khi tổng hợp (Phase 3), với flow có thực chất (track, deep review, init, plan, inbox; trừ dashboard/capture/trace đơn giản), thêm đúng 1 dòng:

> "Muốn rút bài học phiên này? (chạy okr-retro)"

KHÔNG tự chạy. User đồng ý hoặc tự gõ "rút bài học" → chạy `okr-retro` inline.

`okr-retro` ghi 3 loại bài học vào `.okr/lessons/` (skill = công cụ, workflow = bản đồ điều phối, project = tri thức):

- **Loại A (skill/công cụ)**: năng lực harness, luôn shared. Hàng đợi port thủ công về repo gốc `objective-kit`.
- **Loại C (workflow/bản đồ)**: lưỡng tính. Shared = quy trình tổng quát chờ port; local = playbook riêng project, sống tại chỗ.
- **Loại B (project/tri thức)**: dữ kiện tại chỗ, auto-load mỗi phiên qua index.

Record-only: `okr-retro` KHÔNG tự sửa file skill, KHÔNG ghi CHANGELOG. Chi tiết: `okr-retro` SKILL.md.

## Tham khảo

- I/O từng skill: `references/skill-contract.md`
- Sơ đồ luồng: `references/flows.md`