# Framework Issue Resolve

> 上游 GitHub issue 全闭环 — 拉取 → 审查分析 → 给修复意见 → 实施 → 关闭 issue。覆盖 framework-feedback bundle 的整段消化路径，把下游反馈打通到上游 SKILL-IMPROVE 应用 + close。本 skill 仅供 maintainer / fork owner 使用，不是下游业务流程的一部分。

- Skill: `lync-cyber/framework-issue-resolve` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lync-cyber/framework-issue-resolve`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lync-cyber/framework-issue-resolve/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lync-cyber (https://skillmd.com/u/lync-cyber)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lync-cyber/framework-issue-resolve

---


# 框架 issue 闭环消化 (framework-issue-resolve)

## 五步闭环

```
1. 拉取 (fetch)        →  cataforge issue triage [--dry-run]
2. 审查分析 (analyze)  →  draft 落 docs/reviews/triage/SKILL-IMPROVE-<id>-issue-<N>.md
3. 给修复意见 (propose)→  draft 内 verdict + rationale + 修复路径
4. 实施 (implement)   →  feature branch + Edit + commit + PR（标准 dev 流程）
5. 关闭 (close)        →  cataforge issue close <N> --verdict <v> [--pr <P>] [--reason ...]
```

每步之间是 maintainer **强制 checkpoint**：自动化只跨 1↔2 和 5；3↔4 是人工 go/no-go。

## 能力边界

- **能做**: 拉取 + Layer 1 字段解析 + 草稿渲染 + close 模板化（统一文案）
- **不做**: Layer 2 语义分析（仍是基于正则的字段抽取）；自动跨过 maintainer 实施 PR；自动改 issue label（用户/maintainer 手动）

## 审查与修复纪律

Step 2–4 定位与修复前按此自检，规避 LLM 常见误区（「做 A 而非 B」）：

- **先在当前代码复现，再判根因**：用最小路径验证症状在当前版本仍可复现，而非凭 issue 描述或 `confirmed` verdict 直接动手 —— verdict 是 Layer 1 事实核查，不代表根因已定。
- **先查是否已实现**：动手前搜索目标逻辑是否已存在（可能在另一层或另一入口未接通），而非假设缺失即新写。
- **修根因而非症状**：沿调用链 / 数据流定位最深层原因（如 SSOT 违背、生产方与消费方解析不对称），改产生缺陷的一方，而非让消费方容忍坏输入。
- **验证 reporter 建议的前提**：其修复方向可能机制不可行、已被实现或仅触及症状；先核实再决定采纳 / 替代 / 否决，不照搬。
- **核全部入口**：某能力已存在却仍报缺陷时，确认所有调用路径都接通它，而非只改单一入口。
- **修复设计以收敛为准绳**：修复应减少而非增加同一语义在系统中的实现数——不变量只保留一个实现点，置于全部路径必经的最窄处；复用既有机制与信号，删除无生产者 / 无消费者的路径；而非在各入口分别贴补丁、另造检测副本或为死路径保留兼容。
- **可复现缺陷先写失败测试**：先写钉住症状的失败测试（RED）再修（GREEN），把回归固化。

## 输入规范

- `framework.json#upgrade.source.repo` — 拉取目标
- `framework.json#feedback.gh.labels` — 默认 label 过滤集合
- 本地 `.cataforge/skills/*` 和 `.cataforge/agents/*` — id 核对
- `cataforge.__version__` — reported_version vs installed_version 比对

## 输出规范

### Step 2 草稿 frontmatter

```yaml
---
id: skill-improve-<target_id>-issue-<N>
doc_type: skill-improve
status: draft
source_issue: <N>
source_url: https://github.com/<owner>/<repo>/issues/<N>
reported_version: <X.Y.Z>
installed_version: <cataforge.__version__>
verdict: <见下表>
target_id: <skill/agent id, 或 source 文件名>
target_kind: skill | agent | source | schema | mixed | aggregate
target_path: <可选>
rationale: "..."
---
```

### verdict 五态

| verdict | 触发 | 后续动作 |
|---------|------|---------|
| `confirmed` | 引用了存在的 skill/agent/源文件 + reporter version 持平 | 写草稿；步骤 4 实施修复；步骤 5 close --verdict fixed |
| `wontfix-by-design` | maintainer 判定下游误解了主动设计（如带点 doc_id 被框架主动拒绝） | 草稿写出主动设计的 evidence；步骤 5 close --verdict wontfix --reason ... |
| `already-fixed` | reported_version < installed_version（自动判定） | 不写草稿；步骤 5 close --verdict already-fixed --pr <历史 PR> |
| `needs-repro` | body 缺 `cataforge --version` 行 | 不写草稿；评论要求 reporter 重跑 `cataforge feedback bug --gh`，加 label `needs-repro`（手动） |
| `unrelated` | 不像 feedback bundle | 不写草稿；可手动 close 为 off-topic |

> 注：自动 triage 只输出 `confirmed | already-fixed | needs-repro | unrelated`。`wontfix-by-design` 是 maintainer 在审查 confirmed 草稿后人工改写 frontmatter 的二次判定。

## 操作指令

### Step 1+2+3：拉取 + 分析 + 草稿

```bash
cataforge issue triage --dry-run                  # 看 verdict 分布
cataforge issue triage --since 2026-04-01         # 写草稿
cataforge issue triage --repo OWNER/NAME --label feedback   # fork owner 同步上游
```

### Step 4：实施

`confirmed` 草稿走标准 dev 流程：

```bash
git -c user.name=<id> -c user.email=<email> checkout -b <type>/<scope>-<topic>
# Edit / Write / 跑测试
git -c user.name=<id> -c user.email=<email> commit -m "<type>(<scope>): <subject>"
git -c user.name=<id> -c user.email=<email> push -u origin <branch>
gh pr create --title "<type>(<scope>): <subject>" --body "..."
```

`wontfix-by-design` 草稿不实施代码改动，可选地补 docs/reference FAQ 解释为什么。

### Step 5：关闭

```bash
# 修复后
cataforge issue close <issue-id> --verdict fixed --pr <pr-number>
# → comment: "Fixed in <release-tag> (PR #<pr-number>). Triage: docs/reviews/triage/SKILL-IMPROVE-<target-id>-issue-<issue-id>.md"
# <release-tag> 默认取最新 git tag（无则回退已安装版本）；发版 tag 未打时用 --release vX.Y.Z 显式指定即将发布的版本

# wontfix
cataforge issue close <issue-id> --verdict wontfix --reason "<design intent statement>"
# → comment: "Wontfix — by design: <design intent statement>."

# 历史已修
cataforge issue close <issue-id> --verdict already-fixed --pr <pr-number>
# → comment: "Already fixed in <release-tag> (PR #<pr-number>)."

# 干跑：只打印 comment 不真关
cataforge issue close <issue-id> --verdict fixed --pr <pr-number> --dry-run
```

## CLI 行为要点

实现于 `cataforge issue` CLI（非 skill-run Layer 1）：

| 行为 | 严重等级 |
|------|---------|
| gh issue list 拉取 / reported_version vs installed / skill·agent id 存在性 / upstream-gap 信号统计 | info |
| confirmed 写草稿 | fail |
| fixed / already-fixed 必须 `--pr`；wontfix 必须 `--reason` | fail |

## Anti-Patterns

- **跳过 maintainer checkpoint 直接 close**：实施 PR 没合就 `cataforge issue close --verdict fixed` —— 会让下游收到错误的 "fixed in vX.Y.Z" 通知。close 必须在 PR merge **之后**。
- **wontfix 不写 evidence 就 close**：仅靠 `--reason` 一行不足以让下游理解为什么。先用 triage 草稿写完 evidence + 设计意图引用，close comment 链回草稿。
- **不先 `--dry-run` 确认 verdict 分布就批量写草稿**：issue 数量多时大量 triage 草稿文件涌入 `docs/reviews/triage/`；应先 `cataforge issue triage --dry-run` 检查 needs-repro / unrelated 噪声比，再决定是否全量写草稿。
- **把 triage 草稿当 `reflector approved` 用**：它只是 Layer 1 事实核查产出，没经过 reflector evidence ≥2 校验，不能直接当 EXP 经验落地。需走 reflector → docs/reviews/retro/ → `learn: apply EXP-{NNN}` 路径。

## 与下游 framework-feedback 的回路

```
[下游] cataforge feedback bug --gh
   ↓ 创建 GitHub issue（带 framework.json#feedback.gh.labels 中的 label）
[上游] cataforge issue triage
   ↓ 写 docs/reviews/triage/SKILL-IMPROVE-…
[上游] reflector → docs/reviews/retro/
   ↓ apply EXP-NNN
[上游] PR merge
[上游] cataforge issue close <N> --verdict fixed --pr <P>
   ↓
[下游] cataforge upgrade apply
```