raise-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: raise-issue

WHAT

Purpose và context

Purpose 与 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
```
).

Purpose： 将上下文充分的 ISSUE 写入本地 ledger（真实来源）+ index，分配 owner/dispatch，并在存在远程 tracker 时进行镜像，以便其他会话/开发者拉取后通过
```
/fdk
```
或
```
/propose
```
处理。
Trigger（何时使用）：
- 用于提问/设计会话：发现某个 GAP 或技术债，但尚未实施——需要记录足够的上下文，以便其他会话/开发者拉取后处理。
- “raise issue”、“创建 issue”、“为这项工作开启 issue”、“记录这个 gap 以便稍后处理”、“创建 issue 给其他开发者拉取处理”。
- Feature-gap、tech-debt、架构问题、流程改进、Plan-B/optionality。
Non-goals： 不得用于：正在发生的 bug/runtime 故障/regression → 应使用
```
orca-issue
```
（repro-first gate）。当前会话中已经可以立即执行的工作 → 先用
```
propose
```
，然后编码。不执行 push（这是
```
/ship
```
的职责）。

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

与其他 skill 的边界（避免重复前先阅读）

```
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).

```
orca-issue
```
= 处理故障（bug）的流程，强制执行 red→green 复现。raise-issue = 记录面向未来的工作（gap/技术债），无需 repro。
```
propose
```
= 计划在当前会话中立即执行的工作。raise-issue = HANDOFF（交接），有意延后，并可迁移到其他会话/机器/项目。
raise-issue 只负责记录 + 分配。不编码，也不修改其他分支。后续接收者通过
```
/fdk
```
（如果属于 framework）或
```
/propose
```
（如果属于项目 feature）打开。

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

分类（bug → orca-issue）→ 查询 wiki（R7-f）→ ledger draft（真实来源）→ 分配 → ISSUES.md 行 → [按照 issue-tracker.md 合约镜像 tracker] → 提交 ledger → 确认，停止

。

Input và output contract

Input 与 output contract

	Field	Required?	Ý nghĩa
In	mô tả gap/nợ + bằng chứng	có	đủ để người chưa dự phiên hiểu
In	assignee (username)	không	chưa rõ thì hỏi khi mirror
In	hợp đồng `llmwiki/wiki/sources/issue-tracker.md`	không	chưa có → tạo từ mẫu local-markdown
Out	`llmwiki/wiki/sources/draft/DDMMYY-<slug>.md`	có	theo template, có frontmatter OKF + `## Origin`
Out	dòng trong `llmwiki/wiki/sources/ISSUES.md`	có	id · tiêu đề · status · assignee · tracker
Out	issue remote + URL ở cột `tracker`	khi có tracker	body link ngược file ledger
Out	commit ledger (không push)	có	issue chỉ tồn tại khi travel theo repo

	Field	Required?	含义
In	gap/技术债的描述 + 证据	是	足以让未参与该会话的人理解
In	assignee（username）	否	尚不明确时，在镜像前询问
In	合约 `llmwiki/wiki/sources/issue-tracker.md`	否	尚不存在 → 根据 local-markdown 模板创建
Out	`llmwiki/wiki/sources/draft/DDMMYY-<slug>.md`	是	按模板生成，包含 OKF frontmatter + `## Origin`
Out	`llmwiki/wiki/sources/ISSUES.md` 中的一行	是	id · 标题 · status · assignee · tracker
Out	远程 issue + `tracker` 列中的 URL	有 tracker 时	body 反向链接到 ledger 文件
Out	提交 ledger（不 push）	是	issue 只有随仓库迁移时才存在

Rules và capabilities

Rules 与 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.

RULE-01 (MUST)：只记录 + 分配。绝不编码，也不修改其他分支/项目——issue 必须干净地迁移。
RULE-02 (MUST)：上下文必须充分，足以让未参与会话的人理解：列出证据（report/council/ADR），不能假设存在共同记忆。
RULE-03 (MUST)：先查询 wiki（R7-f），避免创建已有 issue 的重复项。
RULE-04 (MUST)：每个 issue 使用一个文件 + 一行 index。不能将多个 issue 塞入同一个文件。
RULE-05 (MUST)：不得自行将 status 提升到
```
open
```
/
```
claimed
```
以上——切换到
```
in-progress
```
/
```
done
```
由接收会话负责。
RULE-06 (MUST)：仅执行任务要求的操作——不做顺手修改。
Capabilities：读取 wiki；在
```
llmwiki/wiki/sources/
```
中写入 ledger + index；在本地提交；根据仓库合约中声明的 adapter，将 issue 写入远程 tracker。

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õ.

如果是 bug/故障 → 在本 skill 中 cancelled，切换到
```
orca-issue
```
。
已有重复 issue（通过 R7-f 查询）→ 不创建，报告 issue 已存在。
没有远程 tracker/CLI → 在 ledger-only 模式下以有限范围视为 succeeded。
当前位于 main 分支且不允许直接提交 → 提交到
```
issue/<DDMMYY-slug>
```
分支，并明确说明。

HOW

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	mô tả	Phân loại foundation/feature-gap/tech-debt/architecture/process	kind	bug → dừng, `orca-issue`
W02	deterministic	kind + từ khoá	Query wiki trước khi viết (R7-f)	link `[[...]]` bối cảnh	trùng → dừng, báo issue có sẵn
W03	judgment	bối cảnh	Viết draft theo template	file ledger	—
W04	judgment	draft	Assign `assignee` + `dispatch` + `entry` , nêu lý do	frontmatter đủ	—
W05	effect	draft	Thêm dòng vào `ISSUES.md`	index	chưa có file → tạo
W06	effect	hợp đồng tracker	Mirror lên tracker remote nếu có (B01)	URL ở cột `tracker`	không có → ledger-only
W07	effect	ledger + index	Commit ledger (không push)	commit	nhánh chính cấm → B02
W08	deterministic	kết quả	Xác nhận id + đường dẫn + link + assignee, dừng	báo cáo	—

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

Phân loại issue:
```
foundation
```
|
```
feature-gap
```
|
```
tech-debt
```
|
```
architecture
```
|
```
process
```
. Nếu là bug → dừng, chuyển sang
```
orca-issue
```
.
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.
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).
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.
Đă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
```
).
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õ.
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õ.
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.

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	描述	分类 foundation/feature-gap/tech-debt/architecture/process	kind	bug → 停止，转到 `orca-issue`
W02	deterministic	kind + 关键词	写入前查询 wiki（R7-f）	上下文链接 `[[...]]`	重复 → 停止，报告 issue 已存在
W03	judgment	上下文	按模板编写 draft	ledger 文件	—
W04	judgment	draft	分配 `assignee` + `dispatch` + `entry` ，并说明原因	frontmatter 完整	—
W05	effect	draft	在 `ISSUES.md` 中添加一行	index	文件尚不存在 → 创建
W06	effect	tracker 合约	如果存在则镜像到远程 tracker（B01）	`tracker` 列中的 URL	不存在 → ledger-only
W07	effect	ledger + index	提交 ledger（不 push）	commit	禁止在 main 上提交 → B02
W08	deterministic	结果	确认 id + 路径 + 链接 + assignee，然后停止	报告	—

各步骤详情（W01–W08 的真实来源）：

分类 issue：
```
foundation
```
|
```
feature-gap
```
|
```
tech-debt
```
|
```
architecture
```
|
```
process
```
。如果是 bug → 停止，切换到
```
orca-issue
```
。
写入前查询 wiki（R7-f）：查找相关的 ADR/concept/draft，既避免重复，也确保上下文准确。将
```
[[...]]
```
链接写入
```
Bối cảnh & bằng chứng
```
部分。
编写 draft
```
llmwiki/wiki/sources/draft/DDMMYY-<slug>.md
```
，按下方模板生成——上下文必须充分，足以让未参与本次会话的人拉取后立即理解（issue 为何存在、证据、范围、完成标准）。
分配：填写
```
assignee
```
（负责人/agent）+
```
dispatch
```
（建议 Claude/opencode/human）+
```
entry
```
（通过
```
/fdk
```
还是
```
/propose
```
打开）。说明选择理由。
登记到 index：在
```
llmwiki/wiki/sources/ISSUES.md
```
中添加一行（如果文件尚不存在，则创建，标题为
```
# Issues — ledger local
```
）。
镜像到远程 tracker（如有）：检测 host + CLI（见下表）；如果存在 → 创建远程 issue（body 反向链接到 ledger 文件），并将 URL 写入
```
tracker
```
列。如果不存在 → 跳过，使用 ledger-only 模式。如果 assignee 尚不明确（username），则询问。
提交 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 只有在随仓库迁移时才是真实来源——如果文件未被 Git 跟踪，其他人拉取后看不到，
```
git log --all
```
为空，即 issue 尚不存在。此步骤不执行 push（那是
```
/ship
```
的工作）；如果当前位于 main 分支且不允许直接提交 → 创建
```
issue/<DDMMYY-slug>
```
分支并提交到该分支，然后明确说明。
确认但不执行：报告 issue id + ledger 路径 + tracker 链接 + assignee。停在这里——实际执行由接收会话负责。

Branches

Branches（分支）

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	capability_optional	`git remote get-url origin` + CLI tracker sẵn có (theo hợp đồng)	tạo issue remote, body link ngược ledger, ghi URL cột `tracker`	không có → ledger-only; chưa rõ assignee → hỏi	W07
B02	conditional_required	đang ở nhánh chính và không được commit thẳng	tạo nhánh `issue/<DDMMYY-slug>` , commit vào đó, nói rõ	—	W08
B03	conditional_required	chưa có `llmwiki/wiki/sources/issue-tracker.md`	tạo từ mẫu local-markdown; có remote GitHub → đề xuất mirror `gh`	—	W06

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	capability_optional	`git remote get-url origin` + 根据合约已存在 tracker CLI	创建远程 issue，body 反向链接到 ledger，并将 URL 写入 `tracker` 列	不存在 → ledger-only；assignee 尚不明确 → 询问	W07
B02	conditional_required	当前位于 main 分支且不允许直接提交	创建 `issue/<DDMMYY-slug>` 分支，提交到该分支，并明确说明	—	W08
B03	conditional_required	尚无 `llmwiki/wiki/sources/issue-tracker.md`	根据 local-markdown 模板创建；存在 GitHub remote → 建议使用 `gh` 镜像	—	W06

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.

写入时，Wiki hook 检查 R9（OKF frontmatter）、R2（

## Origin

）、R5（有效目录）。W07 后，ledger 必须出现在

git log

中。停在 W08——不执行 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.

Positive： “raise issue：skill-search 尚无缓存” → kind
```
tech-debt
```
，查询无重复 →
```
llmwiki/wiki/sources/draft/190926-skill-search-cache.md
```
+ ISSUES.md 行 +
```
gh issue create
```
（body 链接 ledger）→ 提交
```
issue: 190926-skill-search-cache — …
```
→ 报告 id + 链接，停止。
Boundary/failure： “创建 issue：approve 在 prod 上卡住” → 分类为正在发生的 bug → 停止，切换到
```
orca-issue
```
（repro-first），不写入 ledger。

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

Reference — 存储 — 本地 ledger 是真实来源，远程 tracker 是镜像

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.

Issue = 一个 draft 文件：
```
llmwiki/wiki/sources/draft/DDMMYY-<slug>.md
```
（与 propose 位于同一位置，clone 时随仓库迁移——可迁移，不依赖外部 tracker）。它始终是真实来源。
集中索引：
```
llmwiki/wiki/sources/ISSUES.md
```
——每个 issue 一行（id · 标题 · status · assignee · tracker），类似 MEMORY.md。（存放在
```
sources/
```
，而不是
```
wiki/
```
根目录——R5 folder-structure 会阻止放在 root。）
如果存在，则镜像到远程 tracker（以便在 Issues 标签页中显示、分配真实人员并收到 notification）：根据
```
git remote get-url origin
```
+ 已存在的 CLI 自动检测，完成镜像后将链接写入
```
tracker
```
列。Ledger 仍是真实来源；tracker 只是用于协作的副本。

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

Reference — Tracker — 读取仓库的合约，不要在这里硬编码 CLI

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.

在此仓库中，publish/fetch/label/close/claim 的方式都记录在一个按仓库划定的合约文件中——

llmwiki/wiki/sources/issue-tracker.md

（adapter boundary）。本 skill 只说明意图；合约说明方法。更换 tracker（添加 Jira、换成 GitLab）意味着修改该合约，而不是修改本 skill。参见

[[issue-tracker]]

。

尚无合约文件 → 根据模板创建（默认使用 local-markdown：ledger 为源头，无需网络）；存在 GitHub remote → 建议增加
```
gh
```
镜像。
远程 issue 的 body 必须反向链接到 ledger 文件（真实来源）。将 URL 写入
```
tracker
```
列。
5 个标准标签（
```
labels
```
列，默认值为
```
needs-triage
```
）：
```
needs-triage
```
·
```
needs-info
```
·
```
ready-for-agent
```
·
```
ready-for-human
```
·
```
wontfix
```
。只有
```
ready-for-agent
```
才能 dispatch 给 headless CLI；
```
ready-for-human
```
表示必须由人处理。

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

Reference — Wiki hook 会触发阻断——一开始就满足（避免重跑 3 次）

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.

写入时，Wiki hook 会检查：

llmwiki/wiki/

下的所有文件都必须具备：(R9) 文件开头使用 OKF YAML frontmatter（

type/title/status/tags/timestamp/id

）· (R2) 包含用于追溯来源的

## Origin

section · (R5) 位于有效目录中（issue 位于

sources/draft/

，index 位于

sources/

）。下方模板已同时包含这三项。

Reference — Template issue (frontmatter + thân)

Reference — Issue 模板（frontmatter + 正文）

markdown

---
type: issue
kind: foundation | feature-gap | tech-debt | architecture | process
title: "<một câu>"
status: open            # open | claimed | in-progress | done | wontfix
assignee: <tên/agent>   # ai chịu trách nhiệm
dispatch: <Claude | opencode:<model> | human>
entry: /fdk | /propose  # người nhận mở bằng skill nào
priority: P1 | P2 | P3
tags: [issue, <...>]    # R9 OKF
timestamp: <YYYY-MM-DD>
id: <DDMMYY-slug>
source_session: <mô tả ngắn phiên phát hiện>
---

markdown

---
type: issue
kind: foundation | feature-gap | tech-debt | architecture | process
title: "<một câu>"
status: open            # open | claimed | in-progress | done | wontfix
assignee: <tên/agent>   # ai chịu trách nhiệm
dispatch: <Claude | opencode:<model> | human>
entry: /fdk | /propose  # người nhận mở bằng skill nào
priority: P1 | P2 | P3
tags: [issue, <...>]    # R9 OKF
timestamp: <YYYY-MM-DD>
id: <DDMMYY-slug>
source_session: <mô tả ngắn phiên phát hiện>
---

Issue: <tiêu đề>

Vấn đề (một câu)

Bối cảnh & bằng chứng (vì sao issue tồn tại; link [[ADR]]/[[concept]]/report/council)

Phạm vi (đụng file/module/dự án nào; universal hay local)

Không thuộc phạm vi (chống scope-creep)

Hướng gợi ý (không bắt buộc)

Tiêu chí HOÀN THÀNH (kiểm chứng được)

Assign & lý do

Origin (R2 — raise bởi ai/phiên nào, nguồn bằng chứng)

undefined

undefined