# Session 2026-04-23 ~09:00 — Skill governance + 3 ops skill mới

**Focus:** Khảo sát repo skill 3rd party (alirezarezvani/claude-skills),
quyết định KHÔNG bulk-clone, viết 3 skill PROJECT-SPECIFIC bổ sung,
setup quy trình audit định kỳ hàng tháng (rules + cron tự động).

## Outcomes

### A. Khảo sát + quyết định ✓

- Fetch repo `alirezarezvani/claude-skills` qua WebFetch
- 10 nhóm skill (engineering / marketing / product / agents / ...)
- Phát hiện: **phần lớn skill đã có ở user-level rồi** (`code-reviewer`,
  `sql-database-assistant`, `focused-fix`, `senior-frontend`,
  `mcp-builder`, `webapp-testing`, `review`, `security-review`, ...)
- Phần còn lại: doc-dump generic, **không có YAML `when-to-use`**,
  reference Python script aspirational
- **Quyết định: KHÔNG bulk-import**. Lý do:
  - Trùng skill global đã có → bloat trigger
  - Generic không match SOLUTION_ERP-specific (path, version pin, gotcha #)
  - Vô YAML triggers → trigger sai trong session khác
- **Hành động thay thế:** viết 3 skill PROJECT-SPECIFIC encode
  kiến thức SOLUTION_ERP-only

### B. 3 skill ops mới ✓

| Skill | Path | Encode kiến thức gì |
|---|---|---|
| `dependency-audit-erp` | `.claude/skills/dependency-audit-erp/SKILL.md` | dotnet/npm scan + pin constraint MediatR 12.4.1 / Swashbuckle 6.9.0 / Node 20 / TypeScript 6 erasable, dẫn chiếu gotchas, output template, CI integration TODO |
| `ef-core-migration` | `.claude/skills/ef-core-migration/SKILL.md` | 8 migration history (Init → AddVersionedWorkflows), DesignTimeDbContextFactory pattern, 3-file rule, 6 pitfalls cụ thể (cascade vs restrict cho `Contracts.WorkflowDefinitionId` quan trọng), workflow add entity end-to-end, prod apply via idempotent script |
| `iis-deploy-runbook` | `.claude/skills/iis-deploy-runbook/SKILL.md` | 3 IIS site topology, win-acme + NSSM gitea-runner shared VIETREPORT, LibreOffice 25.8.6 headless, debug playbook 500/502/SignalR/login, deploy steps + manual emergency, rotate creds + backup commands, dẫn chiếu gotcha #25/26/28/29 |

Tất cả đều có YAML `when-to-use` triggers (mix tiếng Việt + Anh) để
auto-trigger semantic match.

Sau update: **6 skill project-level** (3 domain + 3 ops).

### C. Skill governance — `docs/rules.md §9` mới ✓

Section đầy đủ về Skills (push "Liên quan" từ §9 → §10):

- **§9.1** — Bảng 6 skill chia 2 nhóm với trigger phrase
- **§9.2** — Nguyên tắc tạo skill mới: project-specific (KHÔNG clone
  generic), encode SOLUTION_ERP-only, YAML `when-to-use` bắt buộc,
  Vietnamese-first
- **§9.3** — Format `SKILL.md` template chuẩn
- **§9.4** — **Workflow audit định kỳ 7 bước:**
  1. Đọc `.claude/skills/README.md`
  2. Cross-check `STATUS.md` Recently Done — feature mới chưa cover
  3. Cross-check `gotchas.md` — gotcha mới có nên gom thành skill
  4. Cross-check `migration-todos.md` Next up — task lớn cần skill
  5. Check repo nguồn 3rd party có skill mới
  6. Đánh giá staleness (path, version, trigger còn đúng)
  7. Action: refresh / add / archive + commit + log
- **§9.5** — 4 anti-patterns (KHÔNG bulk-clone / không tạo skill chỉ
  để có / không copy docs / không bỏ qua skill khi task khớp)

### D. Cadence — Cron tự động hàng tháng ✓

```
Task ID:     solution-erp-skill-audit-monthly
Schedule:    0 9 1 * * (9:00 AM ngày 1 mỗi tháng, local time)
Next run:    Fri, May 1 2026
Notify:      có
```

Self-contained prompt cold-start (không cần context session hiện tại).
Bao gồm:
- Cross-check 7 bước theo §9.4
- Auto-refresh stale skill nhỏ (path, version, trigger)
- CHỈ ĐỀ XUẤT add/archive (cần human approve)
- Log vào `docs/changelog/skill-audit-{YYYY-MM}.md`
- Commit `[CLAUDE] Skill: audit định kỳ YYYY-MM`
- ABORT nếu repo dirty

### E. Touch-points cho session sau ✓

| File | Update |
|---|---|
| `CLAUDE.md` (root) | Block "🛠️ Skills" callout 6 skill + audit cadence + commit scope thêm `Skill` |
| `docs/CLAUDE.md` | Project layout — skill count 6 |
| `docs/HANDOFF.md` | Section A1 — định kỳ audit, lần kế tiếp 2026-05-01 |
| `docs/changelog/migration-todos.md` | Section "Skill governance (recurring)" với checkbox audit hàng tháng |
| `docs/rules.md` | §9 đầy đủ workflow + cadence + anti-patterns; §10 Liên quan thêm link skill index |
| `.claude/skills/README.md` | Bảng 6 skill chia 2 nhóm + nguyên tắc design |

Session mới đọc 4 file đầu (`STATUS.md` / `PROJECT-MAP.md` /
`migration-todos.md` / `workflow-contract.md`) sẽ thấy ngay quy tắc
skills + audit cadence — không cần ai nhắc.

## Commits (chronological)

```
661f859 — Skill: thêm 3 skill ops project-specific (dependency-audit-erp,
          ef-core-migration, iis-deploy-runbook)
b904a25 — Skill: governance + audit định kỳ hàng tháng
          (rules §9 + CLAUDE.md callout + HANDOFF + migration-todos)
```

## Key architectural decisions

1. **NO bulk-clone repo skill 3rd party** — phần lớn doc-dump generic,
   không có `when-to-use`, dễ trigger nhầm. Chỉ extract concept rồi viết
   project-specific.
2. **Skill = project-encoded knowledge** — encode commit convention,
   path, version pin, gotcha #. Generic skill global cover phần phổ
   thông; project skill cover phần chỉ-có-ở-project.
3. **Audit = data-driven** — cross-check STATUS / gotchas / migration-
   todos để biết feature nào CHƯA có skill cover, không phán đoán cảm
   tính.
4. **Cron self-contained prompt** — cold-start không cần session
   context, log vào file để user xem sau, ABORT nếu repo dirty (an toàn).
5. **Auto-refresh nhỏ, đề xuất add/archive** — refresh path/version
   safe vì không thay đổi semantic; add/archive cần human approve vì
   ảnh hưởng trigger map.

## Skill list (sau audit setup này — 6 skill)

**Domain (3 — logic nghiệp vụ):**
- `contract-workflow` — state machine 9 phase + versioned WF + role guard
- `form-engine` — render template docx/xlsx + FieldSpec + DynamicForm + PDF
- `permission-matrix` — role × menu × CRUD + inherit Contracts/Workflows

**Ops (3 — devops + security + schema):**
- `dependency-audit-erp` — npm/dotnet CVE scan respect pin constraint
- `ef-core-migration` — EF Core 10 + 8 migration history + 3-file rule
- `iis-deploy-runbook` — 3 IIS site + win-acme + gitea-runner + debug playbook

## Next session priority

1. **Wait audit fire 2026-05-01** — xem cron có chạy đúng không, log có sạch không
2. UAT 2-3 user thật (vẫn pending từ session trước)
3. Email outbox (chờ SMTP)
4. Roles CRUD (optional)
5. User-kind approver runtime guard
6. Rotate creds + SQL backup schedule