raise-issue

Skill: raise-issue

WHAT

Purpose và context

• Purpose: ghi một ISSUE đủ bối cảnh vào ledger local (nguồn chân lý) + index, assign owner/dispatch, mirror lên tracker remote nếu có, để phiên/dev khác pull về xử lý qua /fdk hoặc /propose.
• Trigger (when to use):
  • Phiên ĐỂ HỎI/thiết kế, phát hiện một GAP hoặc nợ nhưng CHƯA thực hiện — cần ghi lại đủ bối cảnh để phiên/dev khác kéo về làm.
  • "raise issue", "tạo issue", "mở issue cho việc này", "log gap này để sau làm", "issue để dev khác pull về".
  • Feature-gap, tech-debt, câu hỏi kiến trúc, cải tiến quy trình, Plan-B/optionality.
• Non-goals: KHÔNG dùng cho: bug/sự cố runtime/regression đang cháy → đó là orca-issue (repro-first gate). Việc đã sẵn sàng làm ngay trong phiên → đó là propose rồi code. Không push (việc của /ship).

Ranh giới với skill khác (đọc trước khi trùng)

• orca-issue = vòng xử lý SỰ CỐ (bug), bắt buộc tái hiện đỏ→xanh. raise-issue = ghi việc TIẾN VỀ PHÍA TRƯỚC (gap/nợ), không repro.
• propose = plan để LÀM NGAY trong phiên này. raise-issue = HANDOFF, cố ý defer, travel được sang phiên/máy/dự án khác.
• raise-issue chỉ GHI + ASSIGN. Không code, không sửa nhánh khác. Người nhận sau này mở bằng /fdk (nếu là framework) hoặc /propose (nếu là feature dự án).

Mental model

phân loại (bug → orca-issue) → query wiki (R7-f) → ledger draft (nguồn chân lý) → assign → dòng ISSUES.md → [mirror tracker theo hợp đồng issue-tracker.md] → commit ledger → xác nhận, dừng.

Input và output contract

Rules và capabilities

• RULE-01 (MUST): CHỈ ghi + assign. Tuyệt đối không code, không sửa nhánh/dự án khác — issue phải travel sạch.
• RULE-02 (MUST): Bối cảnh đủ cho người-chưa-dự-phiên: nêu bằng chứng (report/council/ADR), không giả định trí nhớ chung.
• RULE-03 (MUST): Query wiki trước (R7-f) để không raise trùng issue đã có.
• RULE-04 (MUST): Mỗi issue một file + một dòng index. Không nhét nhiều issue vào một file.
• RULE-05 (MUST): Không tự nâng status quá open/claimed — chuyển in-progress/done là việc của phiên nhận.
• RULE-06 (MUST): Touch only what the task requires — no opportunistic changes.
• Capabilities: đọc wiki; ghi ledger + index trong llmwiki/wiki/sources/; commit cục bộ; ghi issue lên tracker remote qua adapter khai trong hợp đồng repo.

Failure boundaries

• Là bug/sự cố → cancelled ở skill này, chuyển orca-issue.
• Trùng issue đã có (query R7-f) → không raise, báo issue sẵn có.
• Không có tracker remote/CLI → succeeded hẹp ở chế độ ledger-only.
• Đang ở nhánh chính và không được commit thẳng → commit vào nhánh issue/<DDMMYY-slug> và nói rõ.

HOW

Main workflow

Chi tiết từng bước (nguồn chân lý cho W01–W08):

1. Phân loại issue: foundation | feature-gap | tech-debt | architecture | process. Nếu là bug → dừng, chuyển sang orca-issue.
2. Query wiki trước khi viết (R7-f): tìm ADR/concept/draft liên quan để không trùng và để nêu bối cảnh chính xác. Ghi các link [[...]] vào phần Bối cảnh.
3. Viết draft llmwiki/wiki/sources/draft/DDMMYY-<slug>.md theo template dưới — bối cảnh phải ĐỦ để người chưa dự phiên này pull về là hiểu ngay (vì sao issue tồn tại, bằng chứng, phạm vi, tiêu chí xong).
4. Assign: điền assignee (người/agent chịu trách nhiệm) + dispatch (đề xuất Claude/opencode/human) + entry (mở bằng /fdk hay /propose). Nêu lý do chọn.
5. Đăng ký vào index: thêm một dòng vào llmwiki/wiki/sources/ISSUES.md (tạo file nếu chưa có, header # Issues — ledger local).
6. Mirror lên tracker remote (nếu có): phát hiện host + CLI (bảng trên); nếu có → tạo issue remote (body link ngược file ledger), ghi URL vào cột tracker. Không có → bỏ qua, ledger-only. Hỏi assignee (username) nếu chưa rõ.
7. Commit ledger (GH#99): git add llmwiki/wiki/sources/draft/<DDMMYY-slug>.md llmwiki/wiki/sources/ISSUES.md && git commit -m "issue: <DDMMYY-slug> — <tiêu đề>". Ledger chỉ là nguồn chân lý khi nó travel theo repo — file untracked thì người pull về không thấy, git log --all rỗng, tức issue chưa tồn tại. Không push ở bước này (đó là việc của /ship); nếu đang ở nhánh chính và không được commit thẳng → tạo nhánh issue/<DDMMYY-slug> rồi commit vào đó và nói rõ.
8. Xác nhận, KHÔNG thực hiện: báo lại issue id + đường dẫn ledger + link tracker + assignee. Dừng ở đây — việc thực thi là của phiên nhận.

Branches

Validation và stopping

Hook wiki kiểm R9 (frontmatter OKF), R2 (## Origin), R5 (folder hợp lệ) khi ghi; ledger có trong git log sau W07. Dừng ở W08 — không thực thi issue.

Examples

• Positive: "raise issue: chưa có cache cho skill-search" → kind tech-debt, query không trùng → llmwiki/wiki/sources/draft/190926-skill-search-cache.md + dòng ISSUES.md + gh issue create (body link ledger) → commit issue: 190926-skill-search-cache — … → báo id + link, dừng.
• Boundary/failure: "tạo issue: approve bị treo trên prod" → phân loại là bug đang cháy → dừng, chuyển orca-issue (repro-first), không ghi ledger.

Reference — Nơi lưu — ledger local là NGUỒN CHÂN LÝ, tracker remote là mirror

• Issue = một file draft: llmwiki/wiki/sources/draft/DDMMYY-<slug>.md (cùng chỗ propose, đi theo repo khi clone — travel-được, không phụ thuộc tracker ngoài). Đây luôn là nguồn chân lý.
• Index tập trung: llmwiki/wiki/sources/ISSUES.md — một dòng/issue (id · tiêu đề · status · assignee · tracker), giống MEMORY.md. (Lưu ở sources/ chứ KHÔNG ở wiki/ root — R5 folder-structure chặn root.)
• Mirror lên tracker remote NẾU CÓ (để hiện ở tab Issues, assign người thật, có notification): tự phát hiện theo git remote get-url origin + CLI sẵn có, mirror rồi ghi link vào cột tracker. Ledger vẫn là nguồn chân lý; tracker chỉ là bản sao để phối hợp.

Reference — Tracker — đọc HỢP ĐỒNG của repo, đừng hardcode CLI ở đây

Cách publish/fetch/label/close/claim ở repo này sống trong một file hợp đồng theo repo — llmwiki/wiki/sources/issue-tracker.md (adapter boundary). Skill này chỉ nói ý định; hợp đồng nói cách làm. Đổi tracker (thêm Jira, đổi GitLab) là sửa hợp đồng đó, KHÔNG sửa skill này. Xem [[issue-tracker]].

• Chưa có file hợp đồng → tạo từ mẫu (mặc định local-markdown: ledger là gốc, không cần mạng); có remote GitHub → đề xuất thêm mirror gh.
• Body issue remote PHẢI link ngược về file ledger (nguồn chân lý). Ghi URL vào cột tracker.
• 5 nhãn chuẩn (cột labels, mặc định needs-triage): needs-triage · needs-info · ready-for-agent · ready-for-human · wontfix. Chỉ ready-for-agent mới được dispatch cho CLI headless; ready-for-human là việc phải người.

Reference — Hook wiki sẽ cắn — thoả ngay từ đầu (đỡ 3 lần bật lại)

Mọi file trong llmwiki/wiki/ phải có: (R9) YAML frontmatter OKF ở đầu (type/title/status/tags/timestamp/id) · (R2) section ## Origin truy nguồn · (R5) nằm trong folder hợp lệ (sources/draft/ cho issue, sources/ cho index). Template dưới đã gồm sẵn cả ba.

Reference — Template issue (frontmatter + thân)

---
type: issue
kind: foundation | feature-gap | tech-debt | architecture | process
title