Polygres Retrieval Design

Polygres Retrieval Design

Produce a reviewable plan before retrieval configuration or application work. This skill is advisory: it must not mutate a project directly.

When Polygres MCP tools are available, read references/mcp-tool-contract.md and use discovered read tools for bounded inspection. Call whoami, respect the connection's project boundary, and keep this skill read-only even when change tools are visible.

Workflow

1. Extract the user outcome, authorization, latency, freshness, and expected result shape from the prompt and inspected application. Ask only for a missing fact that changes the recommendation; representative questions are useful evidence, not a mandatory interview.
2. Resolve project mode, then inspect the supplied schema, verified row identifiers, sample data, and existing retrieval configuration. Label missing evidence as unresolved; never infer production facts from a table or column name.
3. Select the smallest sufficient strategy using references/strategy-selection.md. Reject an unsupported strategy rather than inventing a capability.
4. For graph retrieval, apply references/graph-modeling.md. For an existing vector configuration, TSVector, or fuzzy retrieval, apply references/vector-and-text-design.md. When MCP Graph tools are available, also read references/mcp-graph-retrieval.md for evidence and handoff requirements.
5. For pgContext collections, point synchronization, registered filters, or Context retrieval modes, apply references/context-design.md.
6. For multi-stage retrieval or RAG, apply references/hybrid-and-rag-plan.md.
7. Write the result with references/plan-template.md. When called by $polygres-data-pipeline, return the selected and omitted components plus exact public-interface handoffs in a machine-readable section so the caller can continue without another interview.
8. In a design-only request, stop before mutation. In an active data-pipeline setup, return control to the orchestrating skill; its consolidated review and approval govern the implementation.

Design rules

• Prefer relational retrieval for exact predicates, joins, aggregates, and transactions that do not need a retrieval index.
• For a synced project, keep exact SQL, transactions, and source mutations in the source PostgreSQL database. Use only the supported Runtime retrieval and retrieval-configuration surfaces on Polygres.
• Treat graph, vector, text, and Context indexes and point mappings as derived project resources whose readiness and refresh behavior must be validated.
• Use exact schema identifiers and stable row ID values from verified data. Do not use invented row IDs or fuzzy-match schema names.
• Bound graph direction, depth, fan-out, result count, and cycle behavior.
• Record the embedding model, dimensions, metric, input construction, and response to a dimension mismatch or empty embedding.
• Default new semantic retrieval plans to a Polygres AI Context collection. Decide explicitly whether distinct embeddings belong as named vectors in one collection or require separate collection-level source and policy settings. Record any existing pgvector configuration that must remain compatible or needs a migration plan. Never treat those resources as interchangeable. On a synced project, use only an existing synchronized source table and embedding column; do not plan add_column or new_table on the target.
• State TSVector language/configuration choices and fuzzy thresholds.
• For hybrid retrieval, define stage order, provenance, deduplication, authorization, and token budget.
• Include rebuild or reindex triggers, readiness checks, and rollback or fallback behavior.

Boundaries

• This skill must not mutate a project, generate secrets, or claim that a plan has been applied.
• Do not write mutating command examples. Route approved configuration work to $polygres-cli and approved Python integration to $polygres-sdk.
• Filters are not an authorization boundary. Apply access control before data enters retrieval and again when results are resolved.
• If required columns, stable IDs, or a usable sample are absent, make a reversible provisional recommendation when possible. Stop only when the missing evidence makes every safe recommendation invalid.

Completion

Return the completed reviewable plan, the unresolved assumptions, the recommended public-surface handoffs, and the explicit approval needed before any mutation or implementation.