Troubleshooting & Known Issues
Relevant source files
The following files were used as context for generating this wiki page:
This page serves as a comprehensive guide for identifying, diagnosing, and resolving common technical hurdles within the opencode-skills-collection project. It covers systemic vulnerabilities, integration failures, and environment-specific constraints discovered during codebase audits and automated testing phases.
The scope of this documentation includes debugging workflows, mitigation strategies for production risks, and a catalog of known technical debt hotspots. For initial environment setup instructions, please refer to the Onboarding Guide.
Systematic Debugging Workflow
The project utilizes a structured approach to resolve unexpected behaviors, transitioning from symptom observation to root cause analysis. This process ensures that fixes address underlying logic failures rather than surface-level symptoms.
The diagram above illustrates the iterative debugging cycle used to stabilize project components.
Sources: bundled-skills/bug-hunter/SKILL.md:14-114
Evidence Collection Tools
Effective troubleshooting requires multi-layered data gathering across application logs, system journals, and browser developer tools.
- Application Logs: Monitored via
tail -f logs/app.logto capture runtime exceptions. - System Logs: Accessed via
journalctlfor infrastructure-level service failures. - State Inspection: Checking database consistency, local storage, and session cookies to identify data corruption.
Sources: bundled-skills/bug-hunter/SKILL.md:31-50
Common Technical Issues & Resolutions
Based on comprehensive audits, the following categories represent the most frequent sources of failure within the system.
Environment and Database Failures
Database connectivity and configuration errors often stem from mismatched environment variables or pending schema changes.
| Issue | Potential Cause | Recommended Solution |
|---|---|---|
Connection refused | PostgreSQL service not running or Docker container down. | Verify status with pg_isready or docker ps. |
Migrations pending | Database schema out of sync with application code. | Execute bin/rails db:migrate. |
InvalidMessage | Master key mismatch with encrypted credentials. | Regenerate credentials or sync config/master.key. |
Asset not present | Asset pipeline compilation failure. | Run bin/rails assets:clobber then precompile. |
Sources: bundled-skills/readme/SKILL.md:383-433
Dependency and Build Artifacts
Improperly managed build artifacts or missing type definitions can lead to compilation blockers, particularly in TypeScript environments.
- TypeScript Compilation Errors: Often caused by missing
@typespackages (e.g.,cors). - Build Junk: The presence of
.DS_Store,node_modules, or personal notes in source directories can interfere with clean builds. - Vite Cache: Corrupted Vite caches can lead to "Build failed" errors, requiring the removal of
node_modules/.vite.
Sources: bundled-skills/codebase-audit-pre-push/SKILL.md:32-55, bundled-skills/readme/SKILL.md:435-445, bundled-skills/loki-mode/examples/todo-app-generated/TESTING_DOCUMENTATION.md:77-85
Known Production Risks & Vulnerabilities
Audits have identified specific patterns that pose high risks to system stability and security if left unaddressed.
Security Vulnerabilities
The project enforces a zero-tolerance policy for hardcoded secrets and injection risks.
The sequence diagram shows the risk path for SQL injection when parameterized queries are bypassed.
Sources: bundled-skills/vibe-code-auditor/SKILL.md:144-165, bundled-skills/codebase-audit-pre-push/SKILL.md:104-125
Performance Bottlenecks
- N+1 Queries: Loop-based database calls significantly degrade API response times. These must be replaced with
JOINoperations or batch queries. - Unbounded Loops: Infinite loops or
while Trueblocks without explicit break conditions can lead to process hangs. - Blocking I/O: Synchronous calls in asynchronous event loops (e.g.,
requests.getwithout timeouts) can starve the event loop.
Sources: bundled-skills/vibe-code-auditor/SKILL.md:129-142, bundled-skills/codebase-audit-pre-push/SKILL.md:144-156
UI & Documentation Constraints
VitePress & Mermaid Rendering Issues
Integration of Mermaid diagrams within VitePress sites presents specific rendering challenges due to CSS specificity and SSR (Server-Side Rendering) constraints.
- Flicker/Override: Node text in Mermaid often uses inline
styleattributes that ignore external CSS. This requires anonMountedpolling mechanism to force dark-mode colors. - SSR Conflicts:
enhanceApp()fails to render diagrams because the DOM does not exist during server-side processing;setup()must be used instead. - Generic Parameter Crashes: Bare
<T>generics in Markdown can crash the Vue template compiler unless escaped with backticks.
Sources: bundled-skills/wiki-vitepress/SKILL.md:43-70, 110-116
Technical Debt Hotspots
The following structural patterns are identified as "Technical Debt" and should be prioritized for refactoring to prevent future troubleshooting complexity:
- God Objects: Files exceeding 300 lines or classes with more than 20 methods.
- Deep Nesting: Conditional logic nested more than 3-4 levels deep, obscuring control flow.
- Boolean Flag Control: Functions where behavior is toggled via boolean parameters rather than separate, focused implementations.
- Silent Failures: Bare
except:orcatch(e) {}blocks that swallow errors without logging or re-throwing.
Sources: bundled-skills/vibe-code-auditor/SKILL.md:107-127, 167-180
Summary
Troubleshooting within this project requires a disciplined adherence to evidence-based debugging and regular codebase audits. By addressing known issues like N+1 queries, missing input validation, and build artifact pollution, developers can maintain a production-grade environment. All fixes should be accompanied by regression tests to ensure long-term stability.