-
Notifications
You must be signed in to change notification settings - Fork 36
Closed
Labels
Description
Objective
Extract and document the top 20 most common error messages from the codebase with solutions and examples.
Context
This addresses Issue #3 from discussion #2969. Out of 328 error messages in the codebase, zero are documented. This task focuses on documenting the most critical ones first.
Approach
- Search codebase for
errors.Newandfmt.Errorfpatterns - Identify the 20 most user-facing error messages based on:
- Frequency of occurrence in code
- Likelihood of user encountering them
- Complexity requiring explanation
- For each error, document in
docs/src/content/docs/troubleshooting/errors.md:- Error message text
- What causes it
- How to fix it
- Working example (follow stop-time migration pattern)
- Include the exemplary errors mentioned in discussion [Schema Consistency] 🔍 Schema Consistency Check - Required Fields & Error Documentation Gap (Nov 2, 2025) #2969:
- "cannot use 'command' with 'issues' in the same workflow"
- "strict mode: 'network' configuration is required"
- "job name cannot be empty"
- "http MCP tool '%s' missing required 'url' field"
Files to Modify
docs/src/content/docs/troubleshooting/errors.md- Add top 20 error messages
Gold Standard Example
Follow the stop-time deprecation error pattern from compiler.go:
- Clear explanation
- Migration path
- Working code example
- Preserves user's value
Acceptance Criteria
- 20 error messages documented with cause and solution
- Each error includes a code example
- Errors are searchable in documentation
- Documentation follows the stop-time migration pattern
- Documentation builds successfully
Related to [Schema Consistency] 🔍 Schema Consistency Check - Required Fields & Error Documentation Gap (Nov 2, 2025) #2969
AI generated by Plan Command for discussion #2969
Copilot