Skip to content
Skills Library
DevOps & cloud · Analysis

polygres-troubleshooting

/polygres-troubleshooting

Diagnose Polygres MCP, OAuth connections, CLI, Runtime API, projects, jobs, synchronization, migrations, embeddings, and retrieval through public read-only evidence. Use for scope or project-boundary issues, timeouts, partial failures, readiness, generation or query allowances, Context operations, and search quality.

Licence
Apache-2.0
Last repository change
18.09.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
13
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 18.09.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Diagnose Polygres MCP, OAuth connections, CLI, Runtime API, projects, jobs, synchronization, migrations, embeddings, and retrieval through public read-only evidence. Use for scope or project-boundary issues, timeouts, partial failures, readiness, generation or query allowances, Context operations, and search quality.

Original author description

Diagnose Polygres MCP, OAuth connections, CLI, Runtime API, projects, jobs, synchronization, migrations, embeddings, and retrieval through public read-only evidence. Use for scope or project-boundary issues, timeouts, partial failures, readiness, generation or query allowances, Context operations, and search quality.

How it works

  1. Workflow
  2. Evidence rules
  3. Diagnostic report
  4. Boundaries
Original SKILL.md headings · 93 lines, 672 words
SKILL.md preview
---
name: polygres-troubleshooting
description: Diagnose Polygres MCP, OAuth connections, CLI, Runtime API, projects, jobs, synchronization, migrations, embeddings, and retrieval through public read-only evidence. Use for scope or project-boundary issues, timeouts, partial failures, readiness, generation or query allowances, Context operations, and search quality.
---

# Polygres Troubleshooting

Use read-only checks first. Resolve context, preserve evidence, classify the
failure boundary, and recommend the smallest safe correction. Do not mutate
while diagnosing.

When Polygres MCP tools are available, read
[`references/mcp-tool-contract.md`](references/mcp-tool-contract.md), call `whoami`, and use the discovered read
catalog before CLI or SDK fallback. Treat the connection URL restrictions,
OAuth installation, current scopes, project boundary, project mode, and catalog
version as separate diagnostic layers.

## Workflow

1. Read the installed `polygres --help` and command-specific help before using
   a command. Installed behavior is the source of truth for CLI compatibility.
2. Resolve identity, configuration source, and one exact project using
   [`references/context-and-connectivity.md`](references/context-and-connectivity.md). Stop on an ambiguous project.
3. Capture the symptom, timestamp, sanitized command or SDK call, exit code or
   exception type, `request_id`, job ID, and whether pagination returned a
   cursor.
   For generated pipelines, also capture the manifest state, plan digest,
   approved action IDs, checkpoint, and last successfully completed stage.
4. Inspect project and database evidence with
   [`references/projects-and-database.md`](references/projects-and-database.md).
5. If `project_mode` is `synced`, use [`references/synced-projects.md`](references/synced-projects.md) and skip
   target database, row, import, and migration checks.
6. For import job or migration failures, use
   [`references/jobs-and-migrations.md`](references/jobs-and-migrations.md). For graph, vector, text, hybrid, or
   general readiness failures, use [`references/retrieval.md`](references/retrieval.md). For pgContext
   capability, collection, point, operation, recall, or Joint failures, use
   [`references/context.md`](references/context.md).
   For embedding setup, generation, text query models, or usage, use
   [`references/embeddings.md`](references/embeddings.md).
   Use [`references/mcp-retrieval-quality.md`](references/mcp-retrieval-quality.md) for retrieval evaluation through
   MCP and [`references/mcp-operation-recovery.md`](references/mcp-operation-recovery.md) for MCP operation state.
7. Classify the fault as CLI/local configuration, control-plane, Runtime API,
   Postgres/database or pooler, or asynchronous job state. Use
   [`references/errors-and-escalation.md`](references/errors-and-escalation.md) for typed SDK errors and escalation.
8. Re-check status before retry. Recommend the smallest corrective action and
   hand off supported mutations to `$polygres-cli` or application changes to
   `$polygres-sdk`, using the user's existing authorization when it covers the
   action.

For a single-row write that lost the response after submission, treat the
commit outcome as ambiguous unless public evidence resolves it. Do not
automatically retry a row-only insert, upsert, or ignore. For a Context-backed
write, replay the exact request with its exact idempotency key within the
24-hour replay window; the composite ledger prevents another row mutation.
After `ROW_CONTEXT_IDEMPOTENCY_EXPIRED`, inspect the row and Context point before
choosing a new key.

## Evidence rules

- Use only commands confirmed by installed help and public `$polygres-sdk`
  methods. Never guess a private endpoint or use internal observability.
- Preserve request and job IDs exactly. Distinguish absent evidence from a
  successful check.
- Never log a database password, API key, authorization header, connection
  string containing credentials, or full environment output.
- Do not retry validation, authentication, permission, or compatibility errors
  as if they were transient. Classify an embedding failure by its error code:
  allowance exhaustion and provider throttling both use HTTP 429 but have
  different recovery steps. Preserve the idempotency key after a query timeout.
- Do not request approval again for a corrective action already covered by an
  unchanged consolidated pipeline review. Ask again when its project, source
  scope, action set, egress, destructive effect, or plan digest changed.
- Report pagination and partial failure explicitly; a successful first page or
  one healthy subsystem does not prove the whole operation succeeded.

## Diagnostic report

- **Resolved identity:** account identity or the exact reason it is unknown.
- **Resolved project:** exact project ID or the ambiguity that blocked selection.
- **Symptom:** observable failure and affected operation.
- **Observed evidence:** sanitized statuses, exception classes, and timestamps.
- **Likely cause:** evidence-backed classification with confidence.
- **Safe checks performed:** public read-only commands and SDK calls used.
- **Corrective action:** smallest documented action, not yet performed.
- **Approval or escalation:** approval needed or escalation destination.
- **IDs retained:** request IDs, job IDs, and cursors without secrets.
- **Unknowns:** missing, stale, incompatible, or contradictory evidence.

## Boundaries

- Do not mutate while diagnosing, rotate credentials, retry jobs or Context
  operations, apply migrations, reconcile points, rebuild graph resources, or
  start a text, vector, or Context reindex.
- Do not call an undocumented or private route and do not query a private
  observability system.
- Do not claim root cause when evidence supports only a likely boundary.
Files in this package (13)
  • SKILL.md 6 KB
  • agents/openai.yaml 1 KB
  • references/context-and-connectivity.md 1 KB
  • references/context.md 6 KB
  • references/embeddings.md 13 KB
  • references/errors-and-escalation.md 2 KB
  • references/jobs-and-migrations.md 1 KB
  • references/mcp-operation-recovery.md 2 KB
  • references/mcp-retrieval-quality.md 2 KB
  • references/mcp-tool-contract.md 14 KB
  • references/projects-and-database.md 1 KB
  • references/retrieval.md 3 KB
  • references/synced-projects.md 4 KB

Versions

The database has no other skills named polygres-troubleshooting.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 4837ec2fe0b7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100polygres-retrieval-design
    Design and review Polygres retrieval using available read-only MCP evidence across relational, graph, text, hybrid, and Polygres AI Context. Use for retrieval and embedding strategy selection, Context or graph design, grounded RAG planning, and compatibility review before implementation.
  • 100polygres-data-pipeline
    Set up or extend Polygres through available MCP tools and supported fallbacks for ingestion, memory, graph, embeddings, synchronization, retrieval, RAG, and agent integration. Use for personalized recommendations, complete data-pipeline setup, and verification from a short…
  • 100diagnose-ci-failures
    Diagnose CI failures for a PR using the GitHub CLI, extract error logs, and generate a plan to fix them. Use when the user asks to check CI status, pull CI issues, triage test failures, or investigate PR build failures.
  • 100troubleshooting-flows
    Diagnose and resolve Celigo flow failures -- total failures, partial errors, stuck jobs, empty runs, and performance issues. Use when a flow is failing, producing errors, returning no data, or running slowly.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.