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.
- Author
- evokoa ↗
- Repository
- polygres-skills ↗
- Licence
- Apache-2.0
- Last repository change
- 18.09.2026
Assessment and security
- Files in this package
- 13
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 18.09.2026, without references to retired models or APIs.
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
- Workflow
- Evidence rules
- Diagnostic report
- Boundaries
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.