SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillspolygres-retrieval-design

polygres-retrieval-design

Design & creation

View repository

Updated 10-15 21:39

About this skill

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.