engram-issue-creation

适用场景

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

• 创建 GitHub issue（错误报告、功能请求、文档改进或需跟踪的问题）
• 帮助贡献者提交 issue
• 作为维护者，对 issue 进行分类或批准

---

关键规则

1. 已禁用空白 issue — 必须使用匹配的错误、功能、文档或需跟踪问题模板
2. 创建时，每个 issue 都会自动获得 status:needs-review
3. 在打开任何 PR 之前，维护者必须将 status:needs-review 替换为 status:approved
4. 一般问题请前往 Discussions；需要跟踪处理的问题使用 type:question

---

工作流

1. Consider searching existing issues for duplicates
2. Choose the correct template (Bug Report, Feature Request, Documentation Improvement, or Tracked Question)
3. Fill in ALL required fields
4. Submit → issue gets status:needs-review automatically
5. Wait for a maintainer to replace status:needs-review with status:approved
6. Only then open a PR linking this issue

---

Issue 模板

错误报告

模板：.github/ISSUE_TEMPLATE/bug_report.yml 自动添加标签：type:bug、status:needs-review

必填字段

字段	描述
错误描述	清晰描述错误
复现步骤	按编号列出复现步骤
预期行为	预期发生的情况
实际行为	实际发生的情况（包括错误/日志）
操作系统	下拉选项：macOS、Linux 变体、Windows、WSL
Engram 版本	engram version 的输出
Agent / 客户端	下拉选项：Claude Code、OpenCode、Gemini CLI、Cursor、Windsurf、其他

可选字段

字段	描述
相关日志	日志输出（自动格式化为代码块）
补充信息	截图、变通方法、其他信息

示例 — 通过 CLI 提交错误报告

gh issue create --template "bug_report.yml" \
  --title "fix(store): duplicate observations on concurrent saves" \
  --body "
### Bug Description
When two agents save observations concurrently, duplicates are created.

### Steps to Reproduce
1. Start two engram instances pointing to the same DB
2. Both save an observation with the same title simultaneously
3. Query observations — duplicates appear

### Expected Behavior
The second save should upsert, not insert a duplicate.

### Actual Behavior
Two identical observations exist with different IDs.

### Operating System
macOS

### Engram Version
0.3.1

### Agent / Client
Claude Code

### Relevant Logs
\`\`\`
UNIQUE constraint failed: observations.title
\`\`\`
"

---

功能请求

模板：.github/ISSUE_TEMPLATE/feature_request.yml 自动添加标签：type:feature、status:needs-review

必填字段

字段	描述
问题描述	此功能要解决的痛点
建议的解决方案	从用户角度描述其应如何工作
受影响区域	下拉选项：CLI、MCP 服务、TUI、存储、同步、技能、文档、其他

可选字段

字段	描述
考虑过的替代方案	其他方法或变通方案
补充信息	模型图、示例、参考资料

示例 — 通过 CLI 提交功能请求

gh issue create --template "feature_request.yml" \
  --title "feat(cli): add --json flag to mem search" \
  --body "
### Problem Description
When scripting with engram, parsing the human-readable output of mem search is fragile. There's no machine-readable output format.

### Proposed Solution
Add a \`--json\` flag to \`engram mem search\` that outputs results as JSON.

Example:
\`\`\`bash
engram mem search \"auth middleware\" --json
\`\`\`

Expected output:
\`\`\`json
[{\"id\": 42, \"title\": \"JWT auth middleware\", \"type\": \"decision\", ...}]
\`\`\`

### Affected Area
CLI (commands, flags)

### Alternatives Considered
Using \`jq\` to parse the current output, but it's unreliable since the format isn't structured.
"

---

需跟踪的问题

模板：.github/ISSUE_TEMPLATE/tracked_question.yml 自动添加标签：type:question、status:needs-review

仅当问题的答案需要维护者调查、仓库变更或长期有效的决策时，才使用此表单。一般问题和支持请求请前往 Discussions。

必填字段：问题、需要跟踪 issue 的原因，以及受影响区域。补充信息为可选项。

---

标签系统

创建 issue 时自动添加

模板	添加的标签
错误报告	type:bug、status:needs-review
功能请求	type:feature、status:needs-review
文档改进	type:docs、status:needs-review
需跟踪的问题	type:question、status:needs-review

由维护者添加

标签	添加时机
status:approved	接受 issue 并准备实施后 — 此时可以打开 PR
priority:critical	严重错误或紧急功能
priority:high	高优先级
priority:medium	重要但不会阻碍其他工作
priority:low	有则更好
status:possible-duplicate	正在评估是否重复
status:wontfix	关闭且不予实施，包括已确认的重复 issue
resolution:duplicate	关闭后确认重复

---

维护者批准工作流

1. New issue arrives with status:needs-review
2. Review the issue — is it valid, clear, and in scope?
3. If YES → replace status:needs-review with status:approved
4. If NO → comment with reason, close if needed
5. Contributor can now open a PR linking this issue

---

决策树

Is it a bug?                    → Use Bug Report template
Is it a new feature/improvement? → Use Feature Request template
Is it a general question?       → Use Discussions, NOT issues
Is it a tracked question?       → Use the Tracked Question template
Is it a possible duplicate?     → Replace the current status with status:possible-duplicate
Is it a confirmed duplicate?    → Close it, replace evaluation status with status:wontfix, then add resolution:duplicate

---

命令

# Consider searching existing issues before creating to avoid duplicates
gh issue list --search "keyword"

# Create bug report
gh issue create --template "bug_report.yml" --title "fix(scope): description"

# Create feature request
gh issue create --template "feature_request.yml" --title "feat(scope): description"

# Create documentation improvement
gh issue create --template "docs_improvement.yml" --title "docs(scope): description"

# Create tracked question
gh issue create --template "tracked_question.yml" --title "question(scope): description"

# Maintainer: approve an issue
gh issue edit <number> --remove-label "status:needs-review" --add-label "status:approved"

# Maintainer: add priority
gh issue edit <number> --add-label "priority:high"

# Maintainer: replace every active status while evaluating a possible duplicate
set -euo pipefail

other_statuses="$(gh issue view <number> --json labels --jq '.labels[].name | select(startswith("status:") and . != "status:possible-duplicate")')"
status_args=(--add-label "status:possible-duplicate")
if [[ -n "$other_statuses" ]]; then
  status_args+=(--remove-label "${other_statuses//$'\n'/,}")
fi
gh issue edit <number> "${status_args[@]}"

updated_statuses="$(gh issue view <number> --json labels --jq '.labels[].name | select(startswith("status:"))')"
if [[ "$updated_statuses" != "status:possible-duplicate" ]]; then
  echo "status replacement could not be confirmed; stop without retrying" >&2
  exit 1
fi

# Maintainer: close a confirmed duplicate, then replace evaluation status with terminal status and resolution
gh issue close <number> --reason "not planned" --comment "Closing as duplicate of #<canonical>."
gh issue edit <number> --remove-label "status:possible-duplicate" --add-label "status:wontfix,resolution:duplicate"