[Code Quality] Document 8+ missing error messages in troubleshooting guide

[github-actions]

Description

The Error Documentation Consistency Check analysis identified 22+ user-facing error messages that are implemented in code but missing from the troubleshooting documentation. This creates a poor user experience when developers encounter these errors and cannot find guidance.

Critical Missing Error Documentation

1. dispatch-workflow Errors (Security-Critical)

dispatch-workflow: self-reference not allowed (workflow '%s' cannot dispatch itself)
dispatch-workflow: workflow '%s' must be compiled first (run 'gh aw compile %s')
dispatch-workflow: invalid workflow name '%s' (path traversal not allowed)
```

**Location:** `pkg/workflow/dispatch_workflow.go`  
**Impact:** Users encountering infinite loop prevention or security checks have no documentation.

### 2. Template + Import Interaction Error
```
import directives cannot be used inside template regions ({{#if...}}{{/if}}): found '%s' at line %d within template block
```

**Location:** `pkg/parser/import_processor.go`  
**Impact:** Users attempting imports in Handlebars blocks cannot find troubleshooting guidance.

### 3. Cron Expression Validation Errors
```
fuzzy cron expression '%s' must be scattered to proper cron format before compilation
invalid cron expression '%s': must have exactly 5 fields (minute hour day-of-month month day-of-week)
```

**Location:** `pkg/workflow/schedule.go`  
**Impact:** Users with invalid schedule expressions lack format requirements documentation.

### 4. slash_command Field Variant (Incomplete Documentation)
Current docs only cover `command` field conflicts, missing the newer `slash_command` variant:
```
cannot use 'slash_command' with '%s' in the same workflow
```

### 5. GitHub Actions Mutual Exclusivity Errors
```
%s event cannot specify both 'branches' and 'branches-ignore'...
%s event cannot specify both 'paths' and 'paths-ignore'...

Location: pkg/workflow/compiler_events.go

Suggested Changes

Add dedicated sections to docs/src/content/docs/troubleshooting/errors.md:

1. "dispatch-workflow Safe Output Errors" section with all 3 errors
2. "Compilation Errors" - Add template + import limitation with workarounds
3. "Schedule Configuration Errors" - Document cron format requirements
4. Update existing command/slash_command entry to cover both variants
5. "Trigger Filter Errors" - Document mutual exclusivity requirements

Files Affected

• docs/src/content/docs/troubleshooting/errors.md (primary file)

Success Criteria

• All 8+ critical error messages documented with clear explanations
• Each error includes:
  • Clear error message text
  • Root cause explanation
  • Actionable solution with examples
  • Links to relevant configuration documentation
• Documentation follows existing error entry format
• Cross-references added where appropriate
• CI documentation build passes

Source

Extracted from Error Documentation Consistency Check discussion #12133

Priority

High - Directly impacts user experience when troubleshooting errors. Users currently encounter these errors with no documentation to reference.

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 11, 2026, 1:34 AM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster

[copilot-swe-agent]

The agent encountered an error and was unable to start working on this issue: The service is temporarily unavailable. Please try again later.