Description
The compiler implements a sophisticated exception allowing slash_command to coexist with issues/pull_request events when configured for label-only triggers (only labeled or unlabeled types). However, this exception is NOT documented, causing users to avoid valid patterns.
Current State
Implementation: pkg/workflow/compiler_safe_outputs.go:98 via parser.IsLabelOnlyEvent()
Documentation: docs/src/content/docs/reference/command-triggers.md:79 states absolute prohibition
Impact: Users unaware of valid use cases
The Gap
Documentation says:
"Note: You cannot combine slash_command with issues, issue_comment, or pull_request as they would conflict."
Code actually allows:
// Special case: allow issues/pull_request if they only have labeled/unlabeled types
if (eventName == "issues" || eventName == "pull_request") && parser.IsLabelOnlyEvent(eventValue) {
continue // Allow this - it doesn't conflict with command triggers
}Suggested Changes
1. Update Documentation (command-triggers.md)
Add section after line 79:
**Exception for Label-Only Events**: You CAN combine `slash_command` with `issues` or `pull_request` if those events are configured for label-only triggers (`labeled` or `unlabeled` types only).
**Example - Valid Pattern:**
```yaml
---
on:
slash_command: /deploy
issues:
types: [labeled, unlabeled]
---
```
This allows workflows that respond to slash commands while also reacting to label changes.2. Add Example Workflow
Create examples/slash-command-with-labels.md:
---
on:
slash_command: /triage
issues:
types: [labeled]
---
# Issue Triage Workflow
Responds to `/triage` command AND automatically reacts when labels are added.3. Update Schema Description
Add to main_workflow_schema.json slash_command field description:
"Note: Can be combined with issues/pull_request events if those events only use 'labeled' or 'unlabeled' types."
Files Affected
docs/src/content/docs/reference/command-triggers.md (add exception section)examples/slash-command-with-labels.md (new file)pkg/parser/schemas/main_workflow_schema.json (update description)
Success Criteria
Benefits
- Better user experience: Users can leverage valid patterns they're currently avoiding
- Reduced confusion: Clear explanation of nuanced behavior
- Documentation accuracy: Matches implementation reality
Priority
High - Critical documentation gap, implementation already excellent
Estimated effort: 1-2 hours
Source
Extracted from Schema Consistency Checker discussion #11570
Analysis quote:
"Label-Only Exception for Command Triggers NOT DOCUMENTED - Severity: HIGH - Undocumented feature behavior. The documentation states an absolute prohibition but the code implements a nuanced exception. Users are unaware that label-only configurations are actually allowed."
AI generated by Discussion Task Miner - Code Quality Improvement Agent
Description
The compiler implements a sophisticated exception allowing
slash_commandto coexist withissues/pull_requestevents when configured for label-only triggers (onlylabeledorunlabeledtypes). However, this exception is NOT documented, causing users to avoid valid patterns.Current State
Implementation:
pkg/workflow/compiler_safe_outputs.go:98viaparser.IsLabelOnlyEvent()Documentation:
docs/src/content/docs/reference/command-triggers.md:79states absolute prohibitionImpact: Users unaware of valid use cases
The Gap
Documentation says:
Code actually allows:
Suggested Changes
1. Update Documentation (
command-triggers.md)Add section after line 79:
2. Add Example Workflow
Create
examples/slash-command-with-labels.md:3. Update Schema Description
Add to
main_workflow_schema.jsonslash_commandfield description:Files Affected
docs/src/content/docs/reference/command-triggers.md(add exception section)examples/slash-command-with-labels.md(new file)pkg/parser/schemas/main_workflow_schema.json(update description)Success Criteria
Benefits
Priority
High - Critical documentation gap, implementation already excellent
Estimated effort: 1-2 hours
Source
Extracted from Schema Consistency Checker discussion #11570
Analysis quote: