positron-issue-creator

Positron Issue Creator

目的

此技能旨在指导如何为 Positron IDE 仓库撰写高质量的 GitHub issue。确保 issue：

• 起草前已彻底检查是否存在重复项
• 已正确添加标签，便于高效分流
• 包含完整、具体的信息
• 不含不必要的赘述和填充内容
• 能够供开发团队采取行动
• 已准备好由用户手动提交

何时使用此技能

在以下情况下使用此技能：

• 用户明确要求起草、创建、提交或报告 issue
• 用户描述了应记录跟踪的 bug 或功能请求
• 起草文档或改进请求
• 用户说“能否帮我起草一个关于……的 issue”或类似内容

以下情况不要使用此技能：

• 处理 intake 轮值职责（请改用 positron-intake-rotation）
• 回复现有 issue
• 一般的 Positron 开发任务

GitHub 访问政策

读取操作（允许）：

• 通过 gh CLI 搜索现有 issue 和讨论
• 通过 gh CLI 获取仓库标签
• 查看 issue 详情以检查重复项
• 阅读任何公开的仓库信息

写入操作（不允许）：

• 直接通过 gh issue create 创建 issue
• 对 issue 发表评论
• 修改现有 issue 的标签
• 任何其他 GitHub 写入操作

应采取的方式： 将 issue 整理为 Markdown 文件或可直接复制到剪贴板的格式，供用户手动提交。

核心工作流程

重要： 此技能用于准备 issue，供用户手动提交，不会自动创建 GitHub issue。用户完全自主决定是否提交到 GitHub。

每次起草 issue 请求时，请遵循以下工作流程：

1. 收集完整背景信息

开始起草前，确保已掌握所有必要信息。如有需要，请通过多轮提问补充信息。

对于 bug 报告，请获取：

• Positron 版本（在“帮助”>“关于”中查看，或提供具体的 build 编号）
• 操作系统及版本
• 会话详情（R/Python 版本）
• 确切的复现步骤
• 预期行为与实际行为
• 错误消息（来自 UI、Output 面板或 Developer Console）
• 相关截图（如有）

对于功能请求，请获取：

• 对所需功能的清晰描述
• 使用场景（为何需要该功能、它能解决什么问题）
• 建议的行为方式（应如何工作）
• 相关 issue 或其他工具中的示例

缺少信息时，请提出具体问题：

• “你使用的是哪个 Positron 版本？请在‘帮助’>‘关于’中查看。”
• “显示的确切错误消息是什么？”
• “你预期发生什么？实际发生了什么？”
• “能否提供具体的复现步骤？”

切勿臆测。 如果信息不明确，请询问，而不要猜测。

2. 搜索重复项

使用 scripts/search_duplicates.sh 搜索现有 issue 和讨论：

cd /path/to/positron/.claude/skills/positron-issue-creator
./scripts/search_duplicates.sh "keywords from issue"

仔细检查搜索结果：

• 检查未关闭和已关闭的 issue
• 同时查看讨论
• 考虑搜索词的不同变体

向用户展示搜索结果：

• 展示所有可能相关的 issue
• 指出看起来非常相似的 issue
• 请用户确认这些是否为重复项
• 对于无法确定的匹配项，明确询问：“这是否与 #1234 是同一个 issue？”

如果发现重复项：

• 告知用户该 issue 已存在
• 提供现有 issue 的链接
• 如果用户想跟踪此 issue，建议其发表评论或添加 👍 reaction
• 不要创建新 issue

如果未发现重复项：

• 继续起草 issue
• 在草稿中引用任何相关 issue

3. 选择合适的标签

使用 scripts/fetch_labels.sh 获取仓库当前的标签：

cd /path/to/positron/.claude/skills/positron-issue-creator
./scripts/fetch_labels.sh

根据以下内容选择标签：

领域标签（选择 1-2 个）：

• area: console - 控制台/REPL 功能
• area: notebook - Jupyter notebook 集成
• area: editor - 文本编辑器功能
• area: plots - 图表查看器和可视化
• area: data-explorer - 数据查看器和数据探索器
• area: connections - 数据库连接
• area: help - 帮助面板和文档
• area: ui - 常规 UI/UX 问题
• 查看 fetch_labels.sh 中的完整标签列表，了解所有选项

类型标签（选择 1 个）：

• Bug - 功能未按预期工作
• Feature Request - 新功能或增强
• Documentation - 文档改进
• Performance - 功能可用，但速度太慢

其他注意事项：

• 避免添加优先级标签（分诊时设置）
• 不要添加状态标签（由团队设置）
• 如果问题涉及多个组件，可以添加多个领域标签

4. 起草问题

使用 references/issue_templates.md 中的模板作为起点，并根据具体问题进行调整。

需要时加载模板：

• Bug 报告：参考 Bug 报告结构
• 功能请求：参考功能请求结构
• 混合情况：酌情调整

遵循 references/writing_guidelines.md 中的写作指南：

核心原则：

1. 简洁 - 每个字都有其作用
2. 不说废话 - 不要道歉、铺垫或使用不必要的客套话
3. 具体 - 提供确切版本、精确步骤和具体细节
4. 直接 - 开门见山

标题指南：

• Bug：[Component] fails when [condition]
• 功能：Add [feature] to [component]
• 使用完整句子，清楚说明问题
• 便于快速浏览和搜索

正文结构：

1. 问题是什么 - 用 1 句话说明问题本身
2. 原因 - 影响/背景（如果不明显，用 1-2 句话说明）
3. 解决方法 - 步骤或建议的解决方案（使用项目符号）
4. 详情 - 系统信息、错误、截图（按需提供）

Bug 报告示例：

Title: Console freezes when printing dataframes with 100k+ rows

The console becomes unresponsive when printing large dataframes.

## Steps to reproduce

1. Create dataframe: `df = pd.DataFrame({'a': range(100000)})`
2. Print it: `print(df)`
3. Console freezes, UI becomes unresponsive

## System details

- Positron 2024.10.0 Build 123
- macOS 14.5
- Python 3.11.6

## Error messages

Developer Console shows: "Maximum call stack size exceeded"

功能请求示例：

Title: Add keyboard shortcut to insert markdown cell in notebooks

Currently inserting markdown cells requires clicking the dropdown menu.
Keyboard shortcut would improve notebook authoring workflow.

## Proposed behavior

- Add keyboard shortcut (e.g., Cmd+M or Ctrl+M)
- Should work when focus is in notebook
- Should insert cell below current cell

## Context

Similar to Jupyter's 'M' key in command mode. Notebook workflows
frequently alternate between code and markdown cells.

应避免的常见反模式：

• 不必要的背景介绍或铺垫
• 含糊的描述（“无法正常工作”“有时会崩溃”）
• 将多个无关问题合并在一起
• 道歉或过于客套的措辞
• 缺少具体细节（确切版本、错误消息）
• 明明可以简洁表达，却写得冗长

提交前的检查清单：

• 标题完整且具体
• 正文开头直述核心问题
• 复现步骤清晰（针对 Bug）
• 包含系统详情（针对 Bug）
• 错误消息为准确引用
• 没有不必要的废话
• 每句话都有价值
• 主题单一且明确
• 已选择合适的标签

5. 向用户展示草稿

展示完整的问题草稿，包括：

• 标题
• 完整正文
• 建议的标签

询问用户：“这是否准确地描述了问题？在我创建问题之前，你希望做任何修改吗？”

允许用户反复修改：

• 用户可能想调整措辞
• 用户可能想起其他细节
• 用户可能想强调不同方面

根据用户的要求进行修改，并展示更新后的草稿。

6. 准备手动提交问题

用户批准草稿后，询问他们希望如何使用：

询问用户：“你希望我如何准备这个问题？”

• 选项 1： 保存为 Markdown 文件
• 选项 2： 整理为可复制的文本

选项 1：保存为 Markdown 文件

创建包含问题所有详情的 Markdown 文件：

# Create file with timestamp in name for uniqueness
cat > "positron-issue-$(date +%Y%m%d-%H%M%S).md" <<'EOF'
---
title: Issue title here
labels: area: console, Bug
repository: posit-dev/positron
---

Full issue body here
with multiple lines
EOF

保存后：

• 显示文件路径
• 提醒用户在 GitHub 上手动创建问题
• 提供快捷链接：https://github.com/posit-dev/positron/issues/new

选项 2：剪贴板格式

以可直接复制的格式呈现问题：

**Title:**
Issue title here

**Labels:**
area: console, Bug

**Body:**
Full issue body here
with multiple lines

---
Create this issue at: https://github.com/posit-dev/positron/issues/new

呈现后：

• 说明用户应复制此文本
• 提醒他们将其粘贴到 GitHub 的新建问题表单中
• 提醒他们需要在界面中手动选择标签

重要指南

重复项检测

全面搜索，但不要吹毛求疵：

• 使用多种关键词组合进行搜索
• 同时检查问题和讨论
• 查看已关闭的条目（它们可能已修复或被标记为不予处理）

无法确定时：

• 向用户展示可能相似的问题
• 明确询问：“这和你要报告的问题是同一个吗？”
• 宁可创建新问题，也不要错误地将其标记为重复项

收集上下文

绝不猜测或妄下结论：

• 如果不清楚版本，请具体询问
• 如果步骤含糊，请求用户澄清
• 如果错误消息是转述的，请询问准确文本

耐心处理反复确认：

• 用户可能无法立即提供所有信息
• 他们可能需要复现问题才能获取详细信息
• 多问几个问题，也比创建信息不完整的问题要好

写作风格

便于快速浏览：

• 忙碌的开发者需要快速理解问题
• 将最重要的信息放在前面
• 适当使用格式（标题、列表、代码块）

尊重读者的时间：

• 除“感谢报告”外，不要使用不必要的客套话
• 不要使用道歉措辞
• 不要使用营销话术或热情洋溢的表达
• 只提供清晰、客观的信息

表达准确：

• 使用确切版本，不要写“最新”或“近期”
• 准确引用错误消息
• 清晰编号步骤
• 陈述实际行为，而非主观解读

特殊情况

安全问题

如果用户描述了安全漏洞：

1. 不要创建公开问题
2. 告知用户：“这似乎是一个安全问题。请通过 [email protected] 私下报告，而不要创建公开问题”
3. 不要继续创建问题

文档问题

将其视为功能请求，但重点关注：

• 缺少或不正确的文档内容
• 用户会到哪里查找此信息
• 建议的改进

使用 Documentation 类型标签。

性能问题

使用错误报告模板，但重点说明：

• 哪项操作运行缓慢
• 实际耗时与预期耗时的差异
• 包括硬件在内的系统详细信息
• 数据大小或复杂程度

使用 Performance 类型标签。

多个相关问题

如果用户描述了多个相关但各自独立的问题：

1. 识别每个独立问题
2. 向用户说明：“这听起来像是 3 个独立问题。我会逐个帮你创建。”
3. 一次创建一个问题
4. 如果相关，在问题正文中相互引用

脚本参考

scripts/fetch_labels.sh

获取仓库的所有标签，以便分类。

用法：

./scripts/fetch_labels.sh          # Human-readable output
./scripts/fetch_labels.sh --json   # JSON output for parsing

scripts/search_duplicates.sh

搜索可能重复的问题和讨论。

用法：

./scripts/search_duplicates.sh "search terms"
./scripts/search_duplicates.sh "search terms" --limit 30

返回：

• 匹配的问题（开放和已关闭）
• 相关讨论
• 供审核的直接链接

参考资料

起草问题时，请加载以下参考文档：

• references/issue_templates.md - 错误、功能和混合问题的模板
• references/writing_guidelines.md - 详细的写作指南、反面示例和范例

应避免的常见错误

1. 创建重复问题 - 始终先搜索，并向用户展示结果
2. 信息不完整 - 持续提问，直到收集到所有详细信息
3. 写作冗长 - 删除所有赘述，做到直接、具体
4. 标题含糊 - 标题应完整说明问题
5. 一个问题包含多个问题 - 拆分为独立、聚焦的问题
6. 臆测上下文 - 请用户确认不明确的细节
7. 跳过标签 - 始终获取并应用合适的标签
8. 未经用户批准就准备文件 - 准备文件前，始终先展示草稿并获得确认

成功标准

成功的问题草稿意味着：

• 不存在重复问题（或用户已确认这是不同的问题）
• 已包含所有必要信息
• 问题简洁明了，没有冗余内容
• 标题准确概括问题
• 已确定合适的标签
• 用户已批准草稿
• 已按用户偏好的格式准备好问题（Markdown 文件或剪贴板文本）
• 用户清楚如何手动提交到 GitHub

工作流概述

1. Gather Context
   ↓
   Ask specific questions until all info available
   ↓
2. Search Duplicates
   ↓
   Run scripts/search_duplicates.sh
   ↓
   Show results to user, confirm not duplicate
   ↓
3. Select Labels
   ↓
   Run scripts/fetch_labels.sh
   ↓
   Choose appropriate area and type labels
   ↓
4. Draft Issue
   ↓
   Use templates from references/
   ↓
   Follow writing guidelines (terse, specific, direct)
   ↓
5. Present Draft
   ↓
   Show complete draft to user
   ↓
   Iterate based on feedback
   ↓
6. Prepare for Submission
   ↓
   Offer markdown file or clipboard format
   ↓
   Save to file OR format for copying
   ↓
   Provide GitHub link and submission instructions

请记住：目标是起草清晰、可执行的问题，同时尊重报告者的意图和开发团队的时间。用户始终完全掌控最终提交到 GitHub 的内容。