raise-issue

技能：raise-issue

WHAT

用途和背景

• 用途： 将背景充分的 ISSUE 记录到本地 ledger（事实来源）和索引中，分配负责人/派发任务；如有远程跟踪器，则同步到远程跟踪器，供其他会话/开发者通过 /fdk 或 /propose 拉取处理。
• 触发条件（何时使用）：
  • 当前会话用于提问/设计时发现 GAP 或技术债，但尚未着手处理——需要记录充分的背景，供其他会话/开发者拉取处理。
  • “raise issue”“创建 issue”“为这件事开个 issue”“记录这个 gap，之后再处理”“开个 issue 让其他开发者拉取处理”。
  • 功能缺口、技术债、架构问题、流程改进、Plan-B/可选方案。
• **非目标：**不要用于：正在发生的运行时 bug/故障/回归问题 → 应使用 orca-issue（先复现的门槛）。已准备好在当前会话立即处理的工作 → 应使用 propose，然后编写代码。不要推送（由 /ship 负责）。

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

• orca-issue = 故障（bug）处理流程，必须复现从红到绿。raise-issue = 记录向前推进的工作（缺口/技术债），无需复现。
• propose = 在当前会话立即执行的计划。raise-issue = 有意延期的交接，可跨会话/机器/项目传递。
• raise-issue 只负责记录 + 分配。不要编写代码，也不要修改其他分支。后续接手者通过 /fdk（如果是框架）或 /propose（如果是项目功能）开始处理。

思维模型

分类（bug → orca-issue）→ 查询 wiki（R7-f）→ ledger 草稿（事实来源）→ 分配 → ISSUES.md 条目 → [根据 issue-tracker.md 合约同步到跟踪器] → 提交 ledger → 确认并停止。

输入和输出约定

	字段	是否必需？	含义
输入	gap/技术债描述 + 证据	是	足以让未参加当前会话的人理解
输入	assignee（用户名）	否	不明确时，在同步时询问
输入	合约 llmwiki/wiki/sources/issue-tracker.md	否	尚无合约时，根据 local-markdown 模板创建
输出	llmwiki/wiki/sources/draft/DDMMYY-<slug>.md	是	遵循模板，包含 OKF frontmatter 和 ## Origin
输出	llmwiki/wiki/sources/ISSUES.md 中的条目	是	id · 标题 · 状态 · assignee · tracker
输出	远程 issue + tracker 列中的 URL	有跟踪器时	正文链接回 ledger 文件
输出	提交 ledger（不推送）	是	issue 只有随仓库传递时才存在

规则和能力

• RULE-01（必须）：仅记录 + 分配。绝对不要编写代码，也不要修改其他分支/项目——确保 issue 能干净地传递。
• RULE-02（必须）：背景应足以让未参加当前会话的人理解：列出证据（报告/评审会/ADR），不要假设大家有共同记忆。
• RULE-03（必须）：先查询 wiki（R7-f），避免重复提出已有 issue。
• RULE-04（必须）：每个 issue 单独一个文件 + 一条索引条目。不要将多个 issue 塞进一个文件。
• RULE-05（必须）：不要自行将状态提升到 open/claimed 以外——转为 in-progress/done 应由接手会话负责。
• RULE-06（必须）：只修改任务所需内容——不要顺手修改其他内容。
• 能力：读取 wiki；在 llmwiki/wiki/sources/ 中写入 ledger 和索引；本地提交；通过仓库合约中声明的 adapter 将 issue 写入远程跟踪器。

失败边界

• 属于 bug/故障 → 在此技能中标记为 cancelled，转交 orca-issue。
• 与已有 issue 重复（通过 R7-f 查询）→ 不要创建，告知已有 issue。
• 没有远程跟踪器/CLI → 以仅使用 ledger 的模式有限地 succeeded。
• 当前位于主分支且不允许直接提交 → 提交到 issue/<DDMMYY-slug> 分支，并明确说明。

HOW

主工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	判断	描述	将问题分类为 foundation/feature-gap/tech-debt/architecture/process	kind	bug → 停止，转交 orca-issue
W02	确定性	kind + 关键词	写入前先查询 wiki（R7-f）	上下文链接 [[...]]	重复 → 停止，告知已有 issue
W03	判断	上下文	按模板编写草稿	ledger 文件	—
W04	判断	草稿	指定 assignee + dispatch + entry，说明理由	frontmatter 完整	—
W05	效果	草稿	在 ISSUES.md 中添加一行	索引	文件不存在 → 创建
W06	效果	tracker 合约	如有远程 tracker，则镜像到远程 tracker（B01）	tracker 列中的 URL	没有 → 仅记录在 ledger
W07	效果	ledger + 索引	提交 ledger（不推送）	commit	禁止在主分支上提交 → B02
W08	确定性	结果	确认 id + 路径 + 链接 + assignee，然后停止	报告	—

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

1. 分类 issue：foundation | feature-gap | tech-debt | architecture | process。如果是 bug → 停止，转交 orca-issue。
2. 写入前先查询 wiki（R7-f）：查找相关的 ADR/concept/draft，避免重复并准确说明背景。将 [[...]] 链接写入“背景”部分。
3. 编写草稿 llmwiki/wiki/sources/draft/DDMMYY-<slug>.md，使用下方模板——背景必须充分，让未参加本次会议的人拉取后能立即理解（issue 为何存在、证据、范围、完成标准）。
4. 指定负责人：填写 assignee（负责的人员/agent）+ dispatch（建议使用 Claude/opencode/human）+ entry（使用 /fdk 还是 /propose 开始）。说明选择理由。
5. 登记到索引：在 llmwiki/wiki/sources/ISSUES.md 中添加一行（如果文件不存在则创建，标题为 # Issues — ledger local）。
6. 镜像到远程 tracker（如有）：检测 host + CLI（见上表）；如果有 → 创建远程 issue（正文中添加指向 ledger 文件的反向链接），并将 URL 写入 tracker 列。没有 → 跳过，仅记录在 ledger 中。如果 assignee（用户名）不明确，则询问。
7. 提交 ledger（GH#99）：git add llmwiki/wiki/sources/draft/<DDMMYY-slug>.md llmwiki/wiki/sources/ISSUES.md && git commit -m "issue: <DDMMYY-slug> — <标题>"。只有当 ledger 随仓库一起流转时，它才是事实来源——如果文件未被跟踪，拉取的人就看不到，git log --all 为空，也就是说 issue 尚不存在。此步骤不要推送（那是 /ship 的工作）；如果当前在主分支且不允许直接提交 → 创建分支 issue/<DDMMYY-slug>，然后提交到该分支，并明确说明。
8. 确认，不要执行：反馈 issue id + ledger 路径 + tracker 链接 + assignee。到此停止——由接收方会话负责执行。

分支

ID	类型	条件	行为	跳过/失败	汇合
B01	可选能力	git remote get-url origin + 已有 tracker CLI（按合约）	创建远程 issue，正文添加指向 ledger 的反向链接，并将 URL 写入 tracker 列	没有 → 仅记录在 ledger；assignee 不明确 → 询问	W07
B02	条件必需	当前在主分支且不允许直接提交	创建分支 issue/<DDMMYY-slug>，提交到该分支，并明确说明	—	W08
B03	条件必需	不存在 llmwiki/wiki/sources/issue-tracker.md	根据 local-markdown 模板创建；如果有远程 GitHub → 建议使用 gh 镜像	—	W06

验证与停止

写入时，wiki hook 会检查 R9（frontmatter OKF）、R2（## Origin）、R5（文件夹有效）；W07 之后，ledger 必须出现在 git log 中。在 W08 停止——不要执行 issue。

示例

• 正向：“raise issue: skill-search 尚无缓存” → kind 为 tech-debt，查询后确认没有重复 → llmwiki/wiki/sources/draft/190926-skill-search-cache.md + ISSUES.md 中的一行 + gh issue create（正文包含 ledger 链接）→ commit issue: 190926-skill-search-cache — … → 反馈 id + 链接，然后停止。
• 边界/失败：“创建 issue：approve 在 prod 上卡住” → 分类为正在发生的 bug → 停止，转交 orca-issue（优先复现），不记录到 ledger。

参考 — 存放位置 — 本地 ledger 是事实来源，远程 tracker 是镜像

• Issue = 一个 draft 文件：llmwiki/wiki/sources/draft/DDMMYY-<slug>.md（与 propose 存放在一起，clone 时随 repo 一起带走——可迁移，不依赖外部 tracker）。这始终是事实来源。
• 集中索引：llmwiki/wiki/sources/ISSUES.md — 每个 issue 一行（id · 标题 · status · assignee · tracker），类似 MEMORY.md。（存放在 sources/ 而不是 wiki/ 根目录——R5 folder-structure 禁止放在根目录。）
• 如果有远程 tracker，则镜像到远程 tracker（以便显示在 Issues 标签页、分配给真实人员并发送通知）：通过 git remote get-url origin + 现有 CLI 自动检测，镜像后将链接写入 tracker 列。Ledger 仍是事实来源；tracker 只是协作副本。

参考 — Tracker — 阅读 repo 的约定，不要在此处硬编码 CLI

在此 repo 中，发布／获取／添加标签／关闭／认领的方式由一个 repo 级约定文件规定 — llmwiki/wiki/sources/issue-tracker.md（适配器边界）。此 Skill 只说明意图；约定文件说明如何做。更换 tracker（添加 Jira、更换为 GitLab）时，只修改该约定文件，不要修改此 Skill。参见 [[issue-tracker]]。

• 如果约定文件不存在 → 根据模板创建（默认 local-markdown：ledger 是根源，不需要网络）；如果有远程 GitHub → 建议添加 gh 镜像。
• 远程 issue 正文必须反向链接到 ledger 文件（事实来源）。将 URL 写入 tracker 列。
• 5 个标准标签（labels 列，默认为 needs-triage）：needs-triage · needs-info · ready-for-agent · ready-for-human · wontfix。只有 ready-for-agent 才能分派给无头 CLI；ready-for-human 表示必须由人处理的工作。

参考 — wiki hook 会拦截 — 一开始就满足要求（避免反复重启 3 次）

llmwiki/wiki/ 中的所有文件都必须满足：（R9） 开头包含有效的 YAML frontmatter OKF（type/title/status/tags/timestamp/id）· （R2） 包含 ## Origin 溯源章节 · （R5） 位于有效文件夹中（issue 放在 sources/draft/，索引放在 sources/）。下方模板已包含这三项。

参考 — Issue 模板（frontmatter + 正文）

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