Document label-only exception for slash_command triggers

[Copilot]

The compiler allows slash_command to coexist with issues/pull_request events when configured for label-only triggers (labeled/unlabeled types only), but this was undocumented. Users avoided valid patterns believing they were prohibited.

Changes

• Documentation (command-triggers.md): Added exception section explaining when combining is allowed with example
• Example workflow (slash-command-with-labels.md): Demonstrates dual-trigger pattern (manual /triage command + automatic label addition)
• JSON schema (main_workflow_schema.json): Updated slash_command description to note the exception

Example

on:
  slash_command: deploy
  issues:
    types: [labeled, unlabeled]  # Valid: label-only triggers don't conflict

This pattern enables workflows triggered both manually via commands and automatically on label changes.

Implementation note: Exception logic exists in compiler_safe_outputs.go:98 via parser.IsLabelOnlyEvent(). This PR surfaces existing behavior.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Document label-only exception for slash_command triggers</issue_title>
<issue_description>### 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 githubnext/gh-aw#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

Comments on the Issue (you are @copilot in this section)

• Fixes [Code Quality] Document label-only exception for slash_command triggers #11666

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.