heraspec 0.1.13 → 0.1.15

package/dist/core/templates/skills/system-design-skill.vi.md

@@ -0,0 +1,70 @@
+# Kỹ năng: Thiết kế Hệ thống (System Design) (Cross-Cutting)
+
+## Mục đích
+
+Đánh giá các quyết định kiến trúc, thiết kế các API endpoint, mô hình hóa lược đồ dữ liệu (database schemas) và phân tích các yếu tố đánh đổi (trade-offs).
+
+## Khi nào sử dụng
+
+- Khi thiết kế một microservice, hệ thống, hoặc mô hình cơ sở dữ liệu mới
+- Khi định nghĩa các ranh giới API và hợp đồng tích hợp (integration contracts) giữa các component
+- Khi mở rộng quy mô hệ thống và phác thảo các yếu tố đánh đổi giữa mở rộng theo chiều dọc và chiều ngang
+
+## Quy trình từng bước
+
+### Bước 1: Thu thập Yêu cầu & Ràng buộc
+- Liệt kê các yêu cầu chức năng (hệ thống phải làm gì)
+- Liệt kê các yêu cầu phi chức năng (throughput, quy mô, độ trễ, tính sẵn sàng)
+- Xác định các ràng buộc kỹ thuật (năng lực của team, ngân sách, thời gian, công nghệ hiện có)
+
+### Bước 2: Thiết kế Mức Cao (High-Level Design)
+- Phác thảo sơ đồ các component (services, clients, data stores)
+- Phác thảo luồng dữ liệu và vòng đời của request/response
+- Lựa chọn giải pháp lưu trữ (SQL, NoSQL, Cache, Document store)
+
+### Bước 3: Thiết kế Chi tiết & Hợp đồng API
+- Định nghĩa các mô hình schema database và chiến lược đánh index
+- Thiết kế hợp đồng API cụ thể (REST endpoints, cấu trúc GraphQL, đặc tả gRPC)
+- Thiết kế cơ chế xử lý lỗi, chiến lược lưu cache và định nghĩa hàng đợi sự kiện (event queue)
+
+### Bước 4: Phân tích Đánh đổi (Trade-off Analysis)
+- Tài liệu hóa rõ ràng các lựa chọn kiến trúc kèm phân tích đánh đổi (ví dụ: Tối ưu đọc vs. Tối ưu ghi)
+- Xây dựng chiến lược mở rộng (sharding, replication, cơ chế failover)
+
+## Input yêu cầu
+
+- Mục tiêu kiến trúc, đặc tả kỹ thuật hoặc user stories
+- Tải trọng dự kiến (requests mỗi giây, kích thước dữ liệu)
+- Ràng buộc về công nghệ hiện có của dự án
+
+## Output mong đợi
+
+- Tài liệu thiết kế hệ thống bao gồm:
+  - Sơ đồ kiến trúc (ASCII hoặc Mermaid)
+  - Mô hình dữ liệu và DB schema
+  - Đặc tả kỹ thuật các API endpoint
+  - Chiến lược Cache/Queue
+  - Phân tích đánh đổi rõ ràng
+
+## Giọng điệu & Quy tắc
+
+- Mọi quyết định thiết kế đều phải kèm theo phân tích đánh đổi tương ứng.
+- Đảm bảo tính mô-đun của thiết kế và giải thích rõ ranh giới giữa các service.
+- Tránh over-engineering (thiết kế quá phức tạp). Hãy thiết kế cho quy mô 10x nhưng xây dựng cho quy mô 1.5x trước.
+
+## Templates có sẵn
+
+- Không có
+
+## Scripts có sẵn
+
+- Không có
+
+## Ví dụ
+
+Xem thư mục `examples/`.
+
+## Liên kết với các kỹ năng khác
+
+- **documents**: Dùng để tạo tài liệu đặc tả kỹ thuật và sản phẩm.
+- **suggestion**: Dùng để phân tích hệ thống hiện tại và đề xuất cải tiến kiến trúc.

package/dist/core/templates/skills/tech-debt/skill.md

@@ -0,0 +1,70 @@
+# Skill: Technical Debt Management (Cross-Cutting)
+
+## Purpose
+
+Systematically identify, categorize, and prioritize technical debt to manage codebase maintenance and refactoring.
+
+## When to Use
+
+- When conducting code health/quality audits
+- When preparing refactoring proposals
+- When managing maintenance backlogs or prioritizing code quality tasks alongside feature work
+
+## Step-by-Step Process
+
+### Step 1: Identify and Categorize
+- **Code debt**: Duplicated logic, poor abstractions, magic numbers, lack of type safety
+- **Architecture debt**: Tight coupling, monolith splitting needs, wrong database choices
+- **Test debt**: Low coverage, flaky tests, missing integration/E2E test pipelines
+- **Dependency debt**: Outdated libraries, unmaintained packages, security vulnerabilities
+- **Documentation debt**: Outdated READMEs, missing runbooks, undocumented APIs
+
+### Step 2: Evaluate and Score
+Score each item on a 1-5 scale:
+- **Impact**: How much does it slow the development team down? (1-5)
+- **Risk**: What is the likelihood and impact of failure if left unresolved? (1-5)
+- **Effort**: How difficult/expensive is it to fix? (1-5)
+
+### Step 3: Prioritize
+Calculate the priority score using the formula:
+`Priority = (Impact + Risk) x (6 - Effort)`
+*(Note: A lower effort value increases the priority score).*
+
+### Step 4: Plan Remediation
+- Organize prioritized items into a phased remediation backlog
+- Propose refactoring phases that can run incrementally alongside regular feature implementation
+
+## Required Input
+
+- Codebase access or architectural description
+- History of recent outages, deployment issues, or developer complaints
+
+## Expected Output
+
+- Prioritized technical debt registry including:
+  - Technical debt category and description
+  - Impact, Risk, Effort scores, and Priority calculation
+  - Business justification for refactoring
+  - Phased remediation plan
+
+## Tone & Rules
+
+- Avoid subjective complaints. Focus on quantifiable metrics (developer velocity, test failures).
+- Frame refactoring in terms of business value (reduced latency, faster onboarding, lower crash rate).
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **suggestion**: Use to turn tech debt findings into actionable feature suggestions.
+- **sourcecode-analyzer**: Use to automate finding duplicated code and quality violations.

package/dist/core/templates/skills/tech-debt/skill.vi.md

@@ -0,0 +1,70 @@
+# Kỹ năng: Quản lý Nợ Kỹ thuật (Technical Debt Management) (Cross-Cutting)
+
+## Mục đích
+
+Nhận diện, phân loại và ưu tiên hóa nợ kỹ thuật (technical debt) một cách hệ thống để quản lý việc bảo trì và tái cấu trúc (refactoring) mã nguồn.
+
+## Khi nào sử dụng
+
+- Khi thực hiện kiểm toán sức khỏe/chất lượng mã nguồn (code health audits)
+- Khi chuẩn bị các đề xuất tái cấu trúc code (refactoring proposals)
+- Khi quản lý danh sách bảo trì hoặc ưu tiên các nhiệm vụ chất lượng code song song với phát triển tính năng mới
+
+## Quy trình từng bước
+
+### Bước 1: Nhận diện và Phân loại
+- **Code debt**: Trùng lặp logic, trừu tượng hóa kém, magic numbers, thiếu an toàn kiểu dữ liệu (type safety)
+- **Architecture debt**: Các thành phần bị phụ thuộc chặt chẽ (tight coupling), cần chia nhỏ monolith, lựa chọn sai database
+- **Test debt**: Độ bao phủ test thấp, test không ổn định (flaky tests), thiếu luồng test tích hợp/E2E
+- **Dependency debt**: Các thư viện bị lỗi thời, gói package không được duy trì, lỗ hổng bảo mật
+- **Documentation debt**: Tài liệu README cũ, thiếu hướng dẫn vận hành (runbooks), API không được viết tài liệu
+
+### Bước 2: Đánh giá và Chấm điểm
+Chấm điểm cho từng mục nợ kỹ thuật theo thang điểm từ 1-5:
+- **Ảnh hưởng (Impact)**: Nó làm chậm tốc độ phát triển của team đi bao nhiêu? (1-5)
+- **Rủi ro (Risk)**: Khả năng xảy ra và tác động của sự cố nếu không xử lý là gì? (1-5)
+- **Công sức (Effort)**: Độ khó/chi phí để sửa lỗi là bao nhiêu? (1-5)
+
+### Bước 3: Ưu tiên hóa
+Tính điểm ưu tiên (Priority Score) theo công thức:
+`Priority = (Impact + Risk) x (6 - Effort)`
+*(Lưu ý: Công sức càng nhỏ sẽ giúp tăng điểm ưu tiên).*
+
+### Bước 4: Lập Kế hoạch Khắc phục
+- Sắp xếp các mục nợ kỹ thuật đã được ưu tiên vào danh sách xử lý (remediation backlog) theo từng giai đoạn
+- Đề xuất các giai đoạn refactor tăng dần, có thể triển khai xen kẽ với các tác vụ phát triển tính năng thông thường
+
+## Input yêu cầu
+
+- Quyền truy cập mã nguồn hoặc tài liệu mô tả kiến trúc
+- Lịch sử các đợt sập hệ thống gần đây, lỗi deploy hoặc khó khăn từ đội ngũ lập trình viên
+
+## Output mong đợi
+
+- Báo cáo phân loại nợ kỹ thuật bao gồm:
+  - Phân loại và mô tả chi tiết nợ kỹ thuật
+  - Điểm số Ảnh hưởng, Rủi ro, Công sức và điểm Ưu tiên tương ứng
+  - Lý do thuyết phục về mặt nghiệp vụ/kinh doanh (business justification) để refactor
+  - Kế hoạch khắc phục theo từng giai đoạn
+
+## Giọng điệu & Quy tắc
+
+- Tránh các lời phàn nàn chủ quan. Tập trung vào các chỉ số định lượng được (tốc độ code của lập trình viên, tỷ lệ test lỗi).
+- Định hình hoạt động refactoring dựa trên giá trị nghiệp vụ mang lại (giảm độ trễ, onboarding lập trình viên mới nhanh hơn, giảm tỷ lệ crash ứng dụng).
+
+## Templates có sẵn
+
+- Không có
+
+## Scripts có sẵn
+
+- Không có
+
+## Ví dụ
+
+Xem thư mục `examples/`.
+
+## Liên kết với các kỹ năng khác
+
+- **suggestion**: Dùng để chuyển đổi phát hiện nợ kỹ thuật thành các đề xuất tính năng thực thi được.
+- **sourcecode-analyzer**: Dùng để tự động tìm kiếm code trùng lặp và các vi phạm chất lượng code.

package/dist/core/templates/skills/tech-debt-skill.md

@@ -0,0 +1,70 @@
+# Skill: Technical Debt Management (Cross-Cutting)
+
+## Purpose
+
+Systematically identify, categorize, and prioritize technical debt to manage codebase maintenance and refactoring.
+
+## When to Use
+
+- When conducting code health/quality audits
+- When preparing refactoring proposals
+- When managing maintenance backlogs or prioritizing code quality tasks alongside feature work
+
+## Step-by-Step Process
+
+### Step 1: Identify and Categorize
+- **Code debt**: Duplicated logic, poor abstractions, magic numbers, lack of type safety
+- **Architecture debt**: Tight coupling, monolith splitting needs, wrong database choices
+- **Test debt**: Low coverage, flaky tests, missing integration/E2E test pipelines
+- **Dependency debt**: Outdated libraries, unmaintained packages, security vulnerabilities
+- **Documentation debt**: Outdated READMEs, missing runbooks, undocumented APIs
+
+### Step 2: Evaluate and Score
+Score each item on a 1-5 scale:
+- **Impact**: How much does it slow the development team down? (1-5)
+- **Risk**: What is the likelihood and impact of failure if left unresolved? (1-5)
+- **Effort**: How difficult/expensive is it to fix? (1-5)
+
+### Step 3: Prioritize
+Calculate the priority score using the formula:
+`Priority = (Impact + Risk) x (6 - Effort)`
+*(Note: A lower effort value increases the priority score).*
+
+### Step 4: Plan Remediation
+- Organize prioritized items into a phased remediation backlog
+- Propose refactoring phases that can run incrementally alongside regular feature implementation
+
+## Required Input
+
+- Codebase access or architectural description
+- History of recent outages, deployment issues, or developer complaints
+
+## Expected Output
+
+- Prioritized technical debt registry including:
+  - Technical debt category and description
+  - Impact, Risk, Effort scores, and Priority calculation
+  - Business justification for refactoring
+  - Phased remediation plan
+
+## Tone & Rules
+
+- Avoid subjective complaints. Focus on quantifiable metrics (developer velocity, test failures).
+- Frame refactoring in terms of business value (reduced latency, faster onboarding, lower crash rate).
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **suggestion**: Use to turn tech debt findings into actionable feature suggestions.
+- **sourcecode-analyzer**: Use to automate finding duplicated code and quality violations.

package/dist/core/templates/skills/tech-debt-skill.vi.md

@@ -0,0 +1,70 @@
+# Kỹ năng: Quản lý Nợ Kỹ thuật (Technical Debt Management) (Cross-Cutting)
+
+## Mục đích
+
+Nhận diện, phân loại và ưu tiên hóa nợ kỹ thuật (technical debt) một cách hệ thống để quản lý việc bảo trì và tái cấu trúc (refactoring) mã nguồn.
+
+## Khi nào sử dụng
+
+- Khi thực hiện kiểm toán sức khỏe/chất lượng mã nguồn (code health audits)
+- Khi chuẩn bị các đề xuất tái cấu trúc code (refactoring proposals)
+- Khi quản lý danh sách bảo trì hoặc ưu tiên các nhiệm vụ chất lượng code song song với phát triển tính năng mới
+
+## Quy trình từng bước
+
+### Bước 1: Nhận diện và Phân loại
+- **Code debt**: Trùng lặp logic, trừu tượng hóa kém, magic numbers, thiếu an toàn kiểu dữ liệu (type safety)
+- **Architecture debt**: Các thành phần bị phụ thuộc chặt chẽ (tight coupling), cần chia nhỏ monolith, lựa chọn sai database
+- **Test debt**: Độ bao phủ test thấp, test không ổn định (flaky tests), thiếu luồng test tích hợp/E2E
+- **Dependency debt**: Các thư viện bị lỗi thời, gói package không được duy trì, lỗ hổng bảo mật
+- **Documentation debt**: Tài liệu README cũ, thiếu hướng dẫn vận hành (runbooks), API không được viết tài liệu
+
+### Bước 2: Đánh giá và Chấm điểm
+Chấm điểm cho từng mục nợ kỹ thuật theo thang điểm từ 1-5:
+- **Ảnh hưởng (Impact)**: Nó làm chậm tốc độ phát triển của team đi bao nhiêu? (1-5)
+- **Rủi ro (Risk)**: Khả năng xảy ra và tác động của sự cố nếu không xử lý là gì? (1-5)
+- **Công sức (Effort)**: Độ khó/chi phí để sửa lỗi là bao nhiêu? (1-5)
+
+### Bước 3: Ưu tiên hóa
+Tính điểm ưu tiên (Priority Score) theo công thức:
+`Priority = (Impact + Risk) x (6 - Effort)`
+*(Lưu ý: Công sức càng nhỏ sẽ giúp tăng điểm ưu tiên).*
+
+### Bước 4: Lập Kế hoạch Khắc phục
+- Sắp xếp các mục nợ kỹ thuật đã được ưu tiên vào danh sách xử lý (remediation backlog) theo từng giai đoạn
+- Đề xuất các giai đoạn refactor tăng dần, có thể triển khai xen kẽ với các tác vụ phát triển tính năng thông thường
+
+## Input yêu cầu
+
+- Quyền truy cập mã nguồn hoặc tài liệu mô tả kiến trúc
+- Lịch sử các đợt sập hệ thống gần đây, lỗi deploy hoặc khó khăn từ đội ngũ lập trình viên
+
+## Output mong đợi
+
+- Báo cáo phân loại nợ kỹ thuật bao gồm:
+  - Phân loại và mô tả chi tiết nợ kỹ thuật
+  - Điểm số Ảnh hưởng, Rủi ro, Công sức và điểm Ưu tiên tương ứng
+  - Lý do thuyết phục về mặt nghiệp vụ/kinh doanh (business justification) để refactor
+  - Kế hoạch khắc phục theo từng giai đoạn
+
+## Giọng điệu & Quy tắc
+
+- Tránh các lời phàn nàn chủ quan. Tập trung vào các chỉ số định lượng được (tốc độ code của lập trình viên, tỷ lệ test lỗi).
+- Định hình hoạt động refactoring dựa trên giá trị nghiệp vụ mang lại (giảm độ trễ, onboarding lập trình viên mới nhanh hơn, giảm tỷ lệ crash ứng dụng).
+
+## Templates có sẵn
+
+- Không có
+
+## Scripts có sẵn
+
+- Không có
+
+## Ví dụ
+
+Xem thư mục `examples/`.
+
+## Liên kết với các kỹ năng khác
+
+- **suggestion**: Dùng để chuyển đổi phát hiện nợ kỹ thuật thành các đề xuất tính năng thực thi được.
+- **sourcecode-analyzer**: Dùng để tự động tìm kiếm code trùng lặp và các vi phạm chất lượng code.

package/dist/core/templates/skills/templates/accessibility-checklist.md

@@ -1,40 +1,40 @@
-# Accessibility Checklist (WCAG 2.1 AA)
-
-## Perceivable
-
-- [ ] All images have descriptive alt text
-- [ ] Color is not the only means of conveying information
-- [ ] Text contrast ratio meets 4.5:1 for normal text, 3:1 for large text
-- [ ] Content can be resized up to 200% without loss of functionality
-
-## Operable
-
-- [ ] All functionality available via keyboard
-- [ ] No keyboard traps
-- [ ] Focus indicators visible
-- [ ] Sufficient time limits (if any) can be extended
-- [ ] No content that causes seizures (flashing)
-- [ ] Touch targets at least 44x44px
-
-## Understandable
-
-- [ ] Page titles are descriptive
-- [ ] Form inputs have labels
-- [ ] Error messages are clear and helpful
-- [ ] Language of page is declared
-- [ ] Navigation is consistent
-
-## Robust
-
-- [ ] Valid HTML markup
-- [ ] ARIA attributes used correctly (if needed)
-- [ ] Screen reader compatible
-- [ ] Works with assistive technologies
-
-## Additional Best Practices
-
-- [ ] `prefers-reduced-motion` respected
-- [ ] Skip links for keyboard navigation
-- [ ] Logical tab order
-- [ ] Focus management for modals/dialogs
-
+# Accessibility Checklist (WCAG 2.1 AA)
+
+## Perceivable
+
+- [ ] All images have descriptive alt text
+- [ ] Color is not the only means of conveying information
+- [ ] Text contrast ratio meets 4.5:1 for normal text, 3:1 for large text
+- [ ] Content can be resized up to 200% without loss of functionality
+
+## Operable
+
+- [ ] All functionality available via keyboard
+- [ ] No keyboard traps
+- [ ] Focus indicators visible
+- [ ] Sufficient time limits (if any) can be extended
+- [ ] No content that causes seizures (flashing)
+- [ ] Touch targets at least 44x44px
+
+## Understandable
+
+- [ ] Page titles are descriptive
+- [ ] Form inputs have labels
+- [ ] Error messages are clear and helpful
+- [ ] Language of page is declared
+- [ ] Navigation is consistent
+
+## Robust
+
+- [ ] Valid HTML markup
+- [ ] ARIA attributes used correctly (if needed)
+- [ ] Screen reader compatible
+- [ ] Works with assistive technologies
+
+## Additional Best Practices
+
+- [ ] `prefers-reduced-motion` respected
+- [ ] Skip links for keyboard navigation
+- [ ] Logical tab order
+- [ ] Focus management for modals/dialogs
+