ns-postgres-rag

PostgreSQL retrieval（RAG / GraphRAG）

Postgres retrieval の基本方針：pgvector、FTS、エンティティ／エッジ、マルチホップ。

分析します。推奨します。アプリコードは作成しません。 必須レポートの承認後（Retrieval Design Report、および GraphRAG モードで ns-graphrag がインストールされている場合は GraphRAG Process Report）→ ns-spec-driven（Specify / Tasks）。

中心ルール

リンクはクエリ結果であり、テキストからの推論ではありません。ベクトルは候補です。エッジはキー／ルールの確認と、保存されたプロベナンスが揃った後にのみ作成します。パスには必ず path + provenance + confidence を含めます。

標準のホップ（例示のみ、英語の成果物）：company → contract → invoice → payment。GraphRAG Process Report でコーパスのつながりを導出します。

必須：pgvector。Timescale：任意 — 時系列データ量、保持、または時間によるパーティション分割が必要な場合。規模：1MM+ ファイル、ドキュメント間リンク。

適用範囲

Context	Strength
Postgres でのグリーンフィールド検索	DDL を承認済みとみなす前に、ゲート 1～3 を必ず実施
ブラウンフィールドのスキーマ／インデックス	最初に DDL を必ず棚卸しする。類似度をリンクとして扱っていないか診断する
必須レポートが承認済みで、人間がコードを求めている	停止します。 Specify / Tasks は ns-spec-driven が担当します（GraphRAG + ns-graphrag がインストールされている場合は、先に Process Report が必須）

リポジトリを確認します（DDL、マイグレーション、Postgres のバージョン、拡張機能、ソース形式）。リポジトリのツリーから確認できる情報を人間に尋ねないでください。

ルーティング（最初に読む）

Signal	Action
今すぐアプリを実装したい	必須レポートがなければ作成します（Retrieval Design Report、GraphRAG + ns-graphrag の場合は Process Report）。作成済みなら ns-spec-driven に進みます。アプリコードは作成しません
類似度を保存済みのリンクとして使用している	references/anti-patterns.md + references/entity-resolution.md
回答に N≥2 ホップが必要で、つながりを含む単一のドキュメントがない	GraphRAG モード — references/retrieval-decision.md。ns-graphrag がインストールされている場合：Retrieval Design Report の後、ns-spec-driven に進む前に、オントロジー／抽出／回答形式／引用または回答拒否について、そこで作業します（Process Report）
オントロジー、スキーマ固定の抽出、回答形式によるルーティング、引用または回答拒否	インストールされている場合は ns-graphrag を使用します — このスキルではありません
トピック検索、小規模コーパス、ホップのつながりなし	ベクトルのみ — グラフテーブルは作成しません
GitLab ISSUE_URL または SDD のバージョン範囲	../../ns-harness/references/code-skill-routing.md に引き継ぎます

起動（必須）

../../ns-harness/references/session-boot.md を参照してください — Session boot を完全に実施（ブロッキング）。次に以下を確認します。

1. DDL／マイグレーション（テーブル、インデックス、vector、tsvector、エンティティ／エッジ）
2. Postgres のバージョン、拡張機能（pgvector は必須。Timescale は存在する場合、またはゲート 2 の条件に該当する場合）
3. ソース形式、コーパスのパス、推測可能な場合は件数
4. このスキルを続行

成功： ツリーとプロジェクトルールから棚卸しできていること。失敗： スキーマを捏造する、またはリポジトリで確認できる情報を人間に尋ねること。

フロー

起動。ゲート 1 コーパスの棚卸し。ゲート 2 検索方式の決定。Postgres でベクトルのみ または ハイブリッド RRF または GraphRAG。ゲート 3 Retrieval Design Report。人間が承認します。モードがリレーショナル GraphRAG であり、ns-graphrag がインストールされている場合：ns-spec-driven に進む前に、そこで GraphRAG Process Report を作成して承認を得ます。それ以外の場合は ns-spec-driven に進みます（または棚卸しに戻ります）。

ゲート 1 — コーパスの棚卸し（ブロッキング）

リポジトリとデータサンプルから記入します。人間に尋ねるのは、ツリーから確認できない情報だけです。項目：templates/retrieval-design-report.md。方法：references/corpus-assessment.md。

Field	Why
ボリューム（ファイル数、バイト数、チャンクの推定数）	1MM+ でのインデックスとストレージ
増加率／変更可能性	再埋め込み率、アップサートか再構築か
エンティティ密度	グラフテーブルかベクトルのみか
質問の類型	方式
レイテンシ予算（p95）	HNSW／フィルター／ホップ上限

省略不可です。棚卸しが不足している場合、ゲート 2 には進めません。

ゲート 2 — 検索方式の決定（ブロッキング）

ベースモードを必ず 1 つだけ選択してください。マトリクス：references/retrieval-decision.md。

モード	選択する条件
ベクトルのみ	トピック／類似性。ホップチェーンなし
ハイブリッド（tsvector + ベクトル、順位融合）	キーワード + セマンティック。1 つのドキュメントで回答できることが多い
リレーショナル GraphRAG	N≥2 ホップが必要かつチェーン全体を含む単一のドキュメントがない

拡張（追加要素 — ベースモードは変更しません）：none | multi-index | agentic | both。none 以外を選ぶ場合は、選択を正当化する測定済みの症状が必要です。方針：references/retrieval-augmentations.md。デフォルトは none です。症状がないまま積み重ねることは拒否してください。

拡張機能：pgvector は常に使用します。Timescale は references/operations-and-scale.md に記載されている場合に限ります — デフォルトではありません。

完全なレポートの前に、ベースモード + 拡張の固定 + その理由を 1 段落で提示してください。モードが誤っている場合は、DDL で取り繕わず、ゲート 2 を書き直してください。

ゲート 3 — 検索設計レポート

templates/retrieval-design-report.md をコピーします。すべてのセクションを埋めてください。アプリケーションコードは含めません。 SQL は対象となる DDL／クエリの形状であり、リリース済みのマイグレーションではありません。

人間の承認が必要です。却下された場合は、ゲート 1 またはゲート 2 に戻ってください。

モードがリレーショナル GraphRAGで、ns-graphrag がインストールされている場合は、まだ ns-spec-driven に進まないでください — ns-graphrag に従い、GraphRAG プロセスレポート（オントロジー、抽出、永続化モデル、回答形式、引用または回答拒否）を作成してください。両方のレポートが承認されたら、ns-spec-driven に進みます。ns-graphrag がない場合は、その旨を明記し、検索のみの範囲で引き継いでください（プロセス上の不足事項は未解決のままです）。

リファレンスマップ

必要に応じて読み込みます。

リファレンス	読むタイミング
references/corpus-assessment.md	ゲート 1。100 万件以上の見込み
references/retrieval-decision.md	ゲート 2 のベースモード + パーティション分割／Timescale
references/retrieval-augmentations.md	ゲート 2 の拡張（multi-index、agentic）。症状の固定
references/schema-and-indexes.md	対象 DDL、HNSW、フィルター、パーティション分割
references/entity-resolution.md	マージ、エイリアス、根拠のないエッジの禁止
references/ingestion-pipeline.md	抽出、チャンク分割、埋め込み、冪等なアップサート
references/multi-hop-traversal.md	再帰 SQL の上限。会社／契約／請求書／支払い
references/retrieval-contract.md	返却形式。path／provenance／confidence
references/evaluation-and-gates.md	ゴールデン質問、再現率、誤リンク、EXPLAIN
references/operations-and-scale.md	100 万件以上の構築、ストレージ、保持期間、Timescale
references/anti-patterns.md	レポートを完了とする前

スニペット（説明用 SQL／単一の返却型）：templates/snippets/。

ns-spec-driven への引き継ぎ

検索設計レポートの人間による承認後 — モードがリレーショナル GraphRAG で ns-graphrag がインストールされている場合は、GraphRAG プロセスレポートの人間による承認後：

## Retrieval implementation planning
- Report: path/to/retrieval-design-report.md (approved)
- GraphRAG Process Report: path/to/graphrag-process-report.md (approved | N/A if not GraphRAG or skill absent)
- Mode: vector-only | hybrid | relational GraphRAG
- Target DDL: [tables]
- Indexes: [HNSW / GIN / partition]
- Ingestion: [idempotent key + hash]
- Eval gates: [recall@k, path precision, false-link, p95]
- Out of scope for this skill: application code; GraphRAG process when ns-graphrag owns it

Specify／Tasks は ns-spec-driven が担当します。このスキルではアプリケーションコードを書きません。このスキルの depends に ns-graphrag を追加しないでください。

停止条件

条件	対応
人間がアプリケーションの実装を求める	必要なレポートを先に作成します（GraphRAG + ns-graphrag の場合はプロセスレポートも含む）。その後は ns-spec-driven のみ
類似性を保存済みエッジとして提案する	拒否します。候補 + 確認 + 出所情報が必要です
N≥2 ホップの必要がないのにグラフモードを選ぶ	グラフを拒否し、ベクトルまたはハイブリッドを選択します
競合するベクトルストアをデフォルトとして提案する	Postgres + pgvector を使用します
上限のない再帰的ウォーク	深さ、ファンアウト、サイクル、スコアによる枝刈りに上限を設定します
時間的なトリガーがないのに Timescale を使う	推奨しません
インベントリを省略する	ゲート 2 をブロックします

禁止事項

• 検索レイヤーの実装（コンシューマー向けマイグレーション、ワーカー、HTTP）
• 埋め込み距離をリンクとして扱うこと
• 外部グラフストアをデフォルトとすること
• P0 に基づく導出なしに、標準的なホップの例を唯一許可されるコーパスチェーンとして扱うこと
• アプリケーションの言語やフレームワークの名称を挙げること（SQL／DDL は許可。説明用の返却型スニペットは 1 つまで）