[Code Quality] Document label-only exception for slash_command triggers

[github-actions]

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

• Documentation explains label-only exception clearly
• Example workflow demonstrates the pattern
• Schema description updated
• Users understand when combining is allowed vs prohibited
• Implementation quality is no longer hidden from users

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

• expires on Feb 7, 2026, 2:02 PM 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