solution-erp/docs/changelog/sessions/2026-04-23-0900-skill-governance.md

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