Issue Review — AI Agent Review / Audit for Doc-from-Issue

Repo profile — read .claude/repo-profile.md first. This skill is repo-agnostic; arc is the reference implementation. Use the profile's repo_slug, verification_entry, kb_issue, plugin_root (where issue-graph's scripts live), and toolchain wherever this doc shows an arc default. Arc's own provenance for the lessons below is not inlined here (fuller case narratives, where they exist, are under .claude/case-law/).

把一篇 issue 处理到位:读 issue + 引用的 repo 文档/代码 + 已有 comments + 对照已落地的实现/代码/intent,产出带证据的发现,作为 comment 落回 issue(而不是埋在某次对话里)。覆盖五类:

• Doc-review:人起源的新设计在 issue 里被讨论/评审(找漂移、独立发现、reframe)。轻量、讨论导向,产出 = 评审 comment + 拆分建议。
• Doc-audit:repo 里的存量老文档被逐篇审计(对照代码重验、跑测试、给 5 类结论)。有界单元,按价值分档投入。
• System-audit(comprehensive code audit):issue 要求对一个子系统 / 跨平台 parity / runtime 本身做全面代码审计(如「Swift/Kotlin 实现是否落后于 Node/CF 参考」)。无界任务,完整执行是契约——见下「★ System-audit」。
• Research(研究类):issue 要求调研一个外部系统/技术与本系统的结合点(如「研究 perkeep 和 did space 的结合点」)。只产出 comment,绝不改 repo 代码——见下「★ Research」。
• Idea(想法类):issue 是一个内部提案/想法(如「提供一个 DID Space + MCP endpoint 给 loop 里的 agent」)——可能可行、可能不可行、可能太模糊、可能与现有设计矛盾。第一步是 clarify,不是执行;产出 = 评估 comment + 澄清问题,绝不改 repo 代码、不开 spin-off——见下「★ Idea」。

五类共用同一台引擎(读 → 对照现实 → 带证据落 comment),但投入档位和产出形态不同:doc-review 轻、doc-audit 按价值分档、system-audit 必须全量、research 双侧深调但产物只落 comment、idea 对照现有架构评估但产物只落 comment(下面「省 token」那套不适用于 system-audit 和 research/idea 的调研深度)。

怎么判类型:issue 锚定单篇文档 = doc-review / doc-audit;issue 说「comprehensive audit」「review 整个 runtime / 跨平台是否一致」「需要完整 test run」「发现 gap/bug 开 issue」= system-audit;标题带 [research] / 正文是「研究一下 X 和我们的 Y」「调研 X 是否适合我们」= research;标题带 idea: / 正文自称「这是个 idea,首先需要分析可行性和价值」/ 是一段提案性质的构想(常附 Slack/讨论原文,无验收标准、无明确 spec)= idea。拿不准 audit 类就按 system-audit 的高标准做(宁可多投入,不可粗略);拿不准「指令还是想法」就按 idea 处理(先 clarify 的代价远低于把模糊想法当指令执行错方向)。