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 の出力
エージェント／クライアント	ドロップダウン：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、Store、Sync、Skills、Documentation、その他

任意項目

項目	説明
検討した代替案	その他のアプローチや回避策
追加情報	モックアップ、例、参考資料

例 — 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	重複が確認された場合を含め、実装せずにクローズするとき
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"