engram-backlog-triage

使用するタイミング

次の場合にこのスキルを使用します：

• Engram（または任意のリポジトリ）のバックログ全体を監査する
• マージ／変更をリクエスト／クローズ／設計が必要／イシューを承認、の判断を行う
• イシュートラッカーのノイズを取り除く
• 次に対応する項目の優先順位を決める

---

メンテナーの理念（Engram）

これらは譲れないプロダクト価値です。すべてのトリアージ判断は、これらの価値に照らして行います。

原則	実際の意味
ゼロ設定	インストール後、必須のフラグ、環境変数、追加のセットアップなしですぐに動作します。
ローカル優先	データは ~/.engram/engram.db に保存されます。デフォルトではクラウドに依存しません。
単一バイナリ	engram バイナリは1つです。デーモン、サービス、追加プロセスは必要ありません。
ターミナル優先	主な UX は CLI と TUI です。ウェブダッシュボードや Electron は使用しません。
薄いアダプター	プラグインスクリプト（Claude、OpenCode、Gemini、Codex）は薄いシムです。ロジックは Go コアにあります。
イシュー優先	すべての PR は status:approved のイシューにリンクする必要があります。承認済みイシューがなければ PR もありません。
根拠に基づくレビュー	変更をリクエストする場合は、具体的で実行可能な項目を挙げます。「改善が必要」といった曖昧な指摘はしません。
厳密なスコープ	やむを得ない理由なく Engram の対象範囲を広げる機能は却下します。
小さく焦点を絞った貢献	5つの問題を解決する500行の PR よりも、1つの問題を解決する50行の PR を優先します。
曖昧な作業やスコープを逸脱する作業は却下	スコープの拡大につながるイシューや、Engram を別のものに変えてしまう PR はクローズします。

---

対応方針の分類

各イシューまたは PR に、必ず1つだけ対応方針を割り当てます。

対応方針	使用するタイミング
マージ	PR に問題がなく、スコープが適切で、テストに合格し、承認済みイシューにリンクされています。すぐにマージします。
変更をリクエスト	PR の方向性は正しいものの、具体的な修正が必要です。各項目を列挙します。
クローズ	ノイズ、重複、曖昧、スコープ逸脱、承認済みイシューがない、または活動がなく古くなった項目です。
設計が必要	アイデアは妥当ですが、PR を歓迎する前にアーキテクチャ上の決定が必要です。まずディスカッションまたは設計イシューを作成します。
イシューを承認	イシューが妥当かつ明確で、再現可能／具体的であり、スコープ内にあります。status:approved ラベルを追加します。
イシューを却下	曖昧、重複、スコープ逸脱、またはディスカッションで扱うべき項目です。説明を添えてクローズします。

---

運用フェーズ

フェーズ1 — バックログを取得する

# All open issues with labels and comments
gh issue list --repo <owner/repo> --state open \
  --json number,title,labels,author,comments,body \
  --limit 100

# All open PRs with labels and review state
gh pr list --repo <owner/repo> --state open \
  --json number,title,labels,author,body,reviews,commits \
  --limit 50

# Check a specific issue in detail
gh issue view <number> --repo <owner/repo> --json number,title,body,labels,comments

# Check a specific PR in detail
gh pr view <number> --repo <owner/repo> --json number,title,body,labels,files,reviews

フェーズ2 — 各項目を分類する

すべてのイシューについて、次の項目に回答します。

1. Is it a real bug with reproduction steps? → candidate for APPROVE ISSUE
2. Is it a clear feature with a problem statement? → candidate for APPROVE ISSUE
3. Is it vague, a question, or a discussion? → REJECT ISSUE (redirect to Discussions)
4. Is it a duplicate? → REJECT ISSUE (link original, close)
5. Does it break zero-config / local-first / single-binary? → REJECT ISSUE
6. Does it need architectural decision before a PR? → NEEDS DESIGN

すべての PR について、次の項目に回答します。

1. Does it link a status:approved issue? → if not → CLOSE (process violation)
2. Does it have exactly one type:* label? → if not → REQUEST CHANGES
3. Do all 5 CI checks pass? → if not → REQUEST CHANGES (list failures)
4. Is the scope tight (one issue, minimal diff)? → if sprawling → REQUEST CHANGES
5. Does it follow conventional commits + branch naming? → if not → REQUEST CHANGES
6. Is the change correct and well-tested? → if yes → MERGE

フェーズ3 — メンテナーのコメントから理念を読み取る

イシューのコメントから、メンテナー（MEMBER または OWNER の関連付け）の返信を探します。次の点を抽出します。

• メンテナーが何を承認し、どのような表現で位置付けたか
• メンテナーが何を別の場所に案内したか（質問 → ディスカッションなど）
• メンテナーがどのようにスコープを絞ったか（「最適な場所：DOCS.md にセクションを追加する」など）
• メンテナーが何を歓迎し、何を先送りしたか（「追跡できるよう、このイシューはオープンのままにします」など）

こうしたパターンを使って、文書化された理念だけでなく、実際のメンテナーの姿勢に合わせてトリアージを調整します。

# Filter for maintainer responses
gh issue view <number> --repo <owner/repo> --json comments \
  --jq '.comments[] | select(.authorAssociation == "MEMBER" or .authorAssociation == "OWNER") | {author: .author.login, body: .body}'

フェーズ 4 — 優先順位を付ける

各対応区分の中で、項目に順位を付けます。

すぐに対応する項目：

• 再現手順が明確で、関連付けられた PR がまだない実際のバグ
• 正しく、範囲が適切で、ラベルの付与または軽微な修正だけが必要な PR
• 内容が正確で曖昧さのないドキュメント関連の PR

プロセスの阻害要因（パイプラインを修正）：

• status:approved との関連付けがない PR（クローズして理由を説明）
• type:* ラベルがない PR（変更を依頼）
• 7 日を超えて対応を待っている status:needs-review の Issue

実際のバグ（優先度の高い Issue）：

• 再現可能なクラッシュ、データ損失、または主要なワークフローの破損
• 別々のユーザーから、裏付けとなるコメントが複数寄せられている Issue

アーキテクチャに関する提案（別途スケジュールを設定）：

• NEEDS DESIGN タグが付いた Issue
• バイナリのインターフェイス、同期プロトコル、またはプラグイン契約に影響する提案

ノイズ（すぐにクローズ）：

• 再現手順のない Issue
• 需要を示す根拠もなく範囲を広げる機能リクエスト
• Discussions で扱うべき質問
• 曖昧な報告（「動作しません」）

フェーズ 5 — レポートを作成する

構造化されたトリアージレポートを出力します。

## Triage Report — <repo> — <date>

### Summary
- Open issues: N | Open PRs: N
- To merge: N | To request changes: N | To close: N
- To approve: N | To reject: N | Needs design: N

### PRs

| # | Title | Disposition | Reason |
|---|-------|-------------|--------|
| 89 | fix(mcp): update config example | MERGE | Correct, scoped, CI pending only |
| 98 | feat(sync): selective export | REQUEST CHANGES | No approved issue linked |
| 80 | feat(nix): Introduce flake.nix | CLOSE | No approved issue; nix out of scope for single-binary |

### Issues

| # | Title | Disposition | Reason |
|---|-------|-------------|--------|
| 93 | Windows false positive (Defender) | APPROVE ISSUE | Real user-facing bug, 3 confirmations |
| 99 | FTS5 trigram SQL logic error | APPROVE ISSUE | Specific bug, reproducible |
| 104 | Project aliasing system | NEEDS DESIGN | Scope question: conflicts with local-first project name resolution |
| 97 | Auto-generate docs from memory | REJECT ISSUE | Vague scope, no concrete problem statement |
| 81 | Remove Projects / local-only notes | REJECT ISSUE | Ambiguous, belongs in Discussions |

### Suggested Comments

#### PR #N — REQUEST CHANGES
> Thanks for this! A few items before this can merge:
> - [ ] Link an approved issue (`Closes #N`) — no PR can merge without one
> - [ ] Add exactly one `type:*` label
> - [ ] Rebase on `main` to resolve the failing CI check

#### Issue #N — APPROVE ISSUE
> This is clear, reproducible, and in scope. Adding `status:approved` — feel free to open a PR linking this issue.

#### Issue #N — REJECT ISSUE
> Thanks for the report! This looks more like a question/discussion topic than a bug or feature request.
> Please continue the conversation in [Discussions](https://github.com/<owner/repo>/discussions).
> Closing this issue — feel free to re-open if you can reproduce it as a concrete bug with steps.

#### Issue #N — NEEDS DESIGN
> Good idea, but this touches the <area> architecture. Before a PR makes sense here,
> let's nail down the design. I'll leave this open for discussion — feel free to propose
> an approach in the comments.

---

すぐに使えるコマンド

# Approve an issue (add status:approved)
gh issue edit <number> --repo <owner/repo> --add-label "status:approved"

# Add priority to an issue
gh issue edit <number> --repo <owner/repo> --add-label "priority:high"

# Close an issue with a comment
gh issue close <number> --repo <owner/repo> \
  --comment "Thanks! This looks like a discussion topic rather than a bug. Please continue in Discussions: https://github.com/<owner/repo>/discussions"

# Request changes on a PR
gh pr review <number> --repo <owner/repo> --request-changes \
  --body "Please link an approved issue (Closes #N) and add exactly one type:* label."

# Approve a PR
gh pr review <number> --repo <owner/repo> --approve \
  --body "Looks good — scoped, tested, and linked to the approved issue."

# Merge a PR (squash)
gh pr merge <number> --repo <owner/repo> --squash --delete-branch

# Add a label to a PR
gh pr edit <number> --repo <owner/repo> --add-label "type:bug"

# List issues needing review (no status:approved yet)
gh issue list --repo <owner/repo> --label "status:needs-review" --state open

---

再利用可能なプロンプトテンプレート

このブロックをコピーすると、任意のリポジトリでトリアージのワークフローを適用できます。

You are a maintainer triage agent. Your job is to audit the full open issue and PR backlog
for <owner/repo> and produce a disposition report.

## Maintainer Philosophy
<paste the philosophy table from this skill, adapted to the target repo>

## Steps
1. Fetch all open issues: `gh issue list --repo <owner/repo> --state open --json number,title,labels,author,comments,body --limit 100`
2. Fetch all open PRs: `gh pr list --repo <owner/repo> --state open --json number,title,labels,author,body,reviews --limit 50`
3. For each item, check for maintainer comments (authorAssociation: MEMBER or OWNER) to infer current stance.
4. Classify each item as: MERGE / REQUEST CHANGES / CLOSE / NEEDS DESIGN / APPROVE ISSUE / REJECT ISSUE
5. Prioritize within buckets: quick wins → process blockers → real bugs → architectural proposals → noise
6. Output a structured markdown report with a table per section (PRs, Issues) and suggested comment text for each action item.

## Constraints
- Never approve issues that are vague, duplicates, or belong in Discussions
- Never approve PRs without a linked status:approved issue
- Prefer closing noise over leaving it open and unresolved
- Be specific in REQUEST CHANGES — list each item as a checkbox
- Proposed comments must be warm but clear: acknowledge the contribution, explain the reason, offer a path forward

---

トレードオフと前提

• 方針は算出するのではなく、推測します。 メンテナーのコメントが判断の基準であり、文書化された理念は二次的なものです。両者が食い違う場合は、コメントに従います。
• PR では Issue を先に扱うことが必須です。 status:approved の Issue がない PR は、必ず REQUEST CHANGES ではなく CLOSE にします。コントリビューターがプロセス全体を省略したためです。
• ノイズは未対応のままにせず、クローズします。 対応可能な内容がない Issue をオープンのままにすると、質の低い投稿も容認されるという期待をコントリビューターに抱かせます。
• NEEDS DESIGN は、ブロックを伴わない有効な対応です。 コントリビューターの提案を拒否せずに、「良いアイデアですが、今は適切なタイミングではありません」という意図を伝えます。
• このスキルは Engram のワークフローを対象としています。 再利用可能なプロンプトを別のリポジトリに適用する場合は、方針の表とラベルシステムを調整してください。