skills.rest
The-Vibe-Company
The-Vibe-CompanyOFFICIAL
Explore all skills by this author →
WebsiteGitHub

debug-companions-prod

Diagnose production Companions runtime incidents via Railway status, redacted logs, and read-only PostgreSQL queries.

2.4k|292|Updated Feb 7, 2026
Search Tags:#railway#postgreSQL#incident triage#production debugging#read-only queries#credential redaction#Log Analysis
One-click install
npx skills add https://github.com/The-Vibe-Company/companion --skill debug-companions-prod
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debug-companions-prod
Source: https://github.com/The-Vibe-Company/companion/tree/main/.agents/skills/debug-companions-prod
Command: npx skills add https://github.com/The-Vibe-Company/companion --skill debug-companions-prod

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

Production incidents in the Companions Runtime v2 stack — failed Box launches, stalled chats, queued turns that never run, and unhealthy runtime services — are hard to diagnose safely without leaking credentials or accidentally mutating production state. This Skill gives an operator a strictly read-only, credential-redacted debugging toolkit for the Railway-hosted production environment.

Core Features & Use Cases

  • Railway deployment inspection: Check that web, api, worker, and runtime services run the same commit, and fetch filtered, redacted deployment logs per service, companion, turn, or attempt.
  • Named read-only database queries: Run fixed diagnostic queries (gate status, queue health, stuck turns, interrupted turns, operations, instances, decisions) wrapped in BEGIN TRANSACTION READ ONLY with no free-SQL mode.
  • Provider Box inventory: List box.ascii.dev Boxes per Companion and surface duplicate-generation evidence of ambiguous Box creation.
  • Use Case: A member reports their Companion chat died mid-conversation. Run the turn, decisions, and runtime log queries to distinguish decision expiry, pi_event_stream_interrupted, and turn_stalled, then follow the matching runbook section — all without a single mutation.

Quick Start

Ask the assistant to triage production by running railway_status, the gate and health database queries, and the last 30 minutes of runtime error logs for the Companions stack.

Frequently Asked Questions about debug-companions-prod

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a stalled Companion chat in production?▼

Run the turn, decisions, and runtime log queries for the affected turn uuid. The skill distinguishes three signatures: ask_user decision expiry after ten minutes, pi_event_stream_interrupted transport loss, and turn_stalled from the ten-minute inactivity deadline, each with its own runbook path.

How do I check Railway deployment status and logs for a service?▼

Use railway_status.py to see per-service deployment status, commit, and age across web, api, worker, and runtime, with a warning when commits diverge. Use railway_logs.py with --service, --since, and optional companion or turn filters to fetch redacted structured logs.

Can this skill run arbitrary SQL against the production database?▼

No. db_query.py exposes only named, fixed queries such as gate, health, stuck, interrupted, turn, ops, instance, and decisions. Every query runs inside BEGIN TRANSACTION READ ONLY with ROLLBACK, and the connection URL is passed via environment, never argv.

Does the skill ever mutate production state?▼

Only railway_restart.py mutates anything, and it is double-gated behind an explicit flag plus DEBUG_PROD_ALLOW_RESTART=1, prints runbook preconditions, and refuses to touch the release migration service. Everything else is strictly read-only.

Why does the skill refuse to read my credentials file?▼

The optional ~/.companion-prod.env fallback must have mode exactly 0600; anything group- or world-readable is rejected. Process environment variables always take precedence, and only the allowlisted keys are loaded.

What credentials are required to use this debugging skill?▼

You need a Railway API token, Railway project and environment ids, a box.ascii.dev API key, and a read-only PostgreSQL connection URL. All output passes through redaction that strips tokens, signed URLs, JWTs, and database credentials.

Related Skills

Explore More Software Engineering Skills→
ecnepsyroc-botecnepsyroc-bot

railway-deploy

Deploy .NET 8 ASP.NET Core apps to Railway with PostgreSQL and migrations.

Community
Intermediate
KentoShimizuKentoShimizu
7

security-secrets-management

Automate inventory, rotation, and auditability of API keys and certificates.

Community
Advanced
whawkinsivwhawkinsiv
232

monitor

Automate uptime, error tracking, and performance monitoring for web apps.

Community
Advanced
ecnepsyroc-botecnepsyroc-bot

postgres-remote-ops

Execute SQL against remote PostgreSQL instances via Node.js pg scripts and SSH batch files.

Community
Intermediate