Write comprehensive troubleshooting guide for top 20 failure modes#603
Merged
Conversation
- docs/ADAPTER_GUIDE.md: comprehensive comparison matrix covering all 19 adapters (models, reasoning, cost tier, tool support, structured output, MCP, recommended use cases) plus decision tree and custom adapter guide - scripts/generate_openapi.py: regenerates docs/openapi.json from the FastAPI app definition without starting the server; updates are picked up automatically by the Redoc page at docs/api-reference.html - docs/openapi-reference.md: updated generation instructions to reference the new script Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…export ENT-003: verify_on_startup() exists but is dead code — spec documents wiring into orchestrator.run() startup sequence, failure modes, and bulletin posting on integrity violations. ENT-004: current export is raw JSONL — spec adds SOC 2 control mappings (CC6.1-CC8.1), evidence summaries, Merkle root attestation, and structured JSON formatting for auditor consumption. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Non-interactive environments (GitHub Actions, GitLab CI, Docker) need BERNSTEIN_NO_TUI=true to prevent terminal escape codes from polluting logs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…E.md The Mermaid state diagram and transition table were missing the `WAITING_FOR_SUBTASKS → BLOCKED` transition (subtask timeout escalation), which is defined in lifecycle.py line 181. Added it back to match the code. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
chernistry
added
bernstein
Contributor
AI Review (Gemini)Gemini review could not be generated (HTTP 503). |
Contributor
AI Review (GitHub Models)SummaryThe pull request aims to add a comprehensive troubleshooting guide that outlines the top 20 failure modes encountered in the Bernstein orchestrator. This documentation will enhance user experience by providing quick references for common issues, thus reducing support requests and improving user satisfaction. Risk AssessmentLow: The addition of a troubleshooting guide does not affect the core functionality of the codebase, nor does it introduce any new dependencies or security vulnerabilities. It primarily serves as supplementary documentation. Actionable Recommendations
|
Code Review SummaryStatus: No Issues Found | Recommendation: Merge Files Reviewed (6 files)
Reviewed by grok-code-fast-1 · 200,291 tokens |
Contributor
CI Summary
Coverage and detailed reports are available via Codecov and the Checks tab. |
|
chernistry
added a commit
that referenced
this pull request
Apr 30, 2026
) * docs: add adapter selection guide + OpenAPI auto-gen script - docs/ADAPTER_GUIDE.md: comprehensive comparison matrix covering all 19 adapters (models, reasoning, cost tier, tool support, structured output, MCP, recommended use cases) plus decision tree and custom adapter guide - scripts/generate_openapi.py: regenerates docs/openapi.json from the FastAPI app definition without starting the server; updates are picked up automatically by the Redoc page at docs/api-reference.html - docs/openapi-reference.md: updated generation instructions to reference the new script Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: add workflow specs for ENT-003 audit integrity + ENT-004 SOC 2 export ENT-003: verify_on_startup() exists but is dead code — spec documents wiring into orchestrator.run() startup sequence, failure modes, and bulletin posting on integrity violations. ENT-004: current export is raw JSONL — spec adds SOC 2 control mappings (CC6.1-CC8.1), evidence summaries, Merkle root attestation, and structured JSON formatting for auditor consumption. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: add BERNSTEIN_NO_TUI to CI and Docker deployment examples Non-interactive environments (GitHub Actions, GitLab CI, Docker) need BERNSTEIN_NO_TUI=true to prevent terminal escape codes from polluting logs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * [WIP] architect-747e986d partial work * docs: fix missing WAITING_FOR_SUBTASKS→BLOCKED transition in LIFECYCLE.md The Mermaid state diagram and transition table were missing the `WAITING_FOR_SUBTASKS → BLOCKED` transition (subtask timeout escalation), which is defined in lifecycle.py line 181. Added it back to match the code. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Write comprehensive troubleshooting guide for top 20 failure modes
Write comprehensive troubleshooting guide for top 20 failure modes
Description
Users encounter failures (adapter not found, rate limits, merge conflicts, budget exceeded, permission denied) and have no centralized troubleshooting resource. Write a guide with: symptom, cause, diagnosis steps, and resolution for each failure mode.
Role: docs
Model: sonnet
Generated by Bernstein — task
de5638da4497