Document label guidelines for AI-generated workflow tracking

[Copilot]

The repository shows 45.7% of open issues with plan and ai-generated labels, raising concerns about label utility. Analysis reveals this is intentional: these labels track AI-generated planning issues from the Plan Command workflow, with perfect overlap indicating healthy automation.

Changes

Created comprehensive label guidelines in specs/labels.md:

• Label taxonomy - Type, Priority, Component, Workflow, and Status categories
• Usage patterns - When to add/remove labels, lifecycle management for AI-generated vs manual issues
• Filtering examples - Combining labels for effective triage (e.g., label:plan label:testing for AI-generated test plans)
• Hygiene practices - Avoiding label overload, maintaining 2-4 labels per issue
• Label distribution analysis - Documentation of current state and recommendations

Updated CONTRIBUTING.md:

• Added references to the label guidelines spec in "Reporting Issues" section
• Added references to the label guidelines spec in "Suggesting Features" section

Key Findings

No taxonomy changes needed. The workflow labels serve their purpose:

• Clear separation between automated and manual issues
• Effective filtering via label combinations
• Zero unlabeled issues (excellent hygiene)
• Additional labels (type, component, priority) provide needed categorization

Optional enhancement: Remove plan label after sub-tasks complete to make it an "active planning" indicator while retaining ai-generated for historical tracking.

Not recommended: Creating plan-* subcategories adds complexity without benefit. Use is:open/is:closed filters instead.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Review and rebalance label distribution</issue_title>
<issue_description>## Objective

Address label skew where 124 issues each have plan and ai-generated labels, limiting the usefulness of these labels for filtering and triage.

Context

Current label distribution shows heavy concentration:

• plan: 124 issues
• ai-generated: 124 issues
• Other labels: distributed across remaining issues

When labels apply to >50% of issues, they lose filtering value.

Approach

1. Analyze label usage patterns:

   gh issue list --label plan --limit 200 --json number,title,labels
   gh issue list --label ai-generated --limit 200 --json number,title,labels

2. Review if plan and ai-generated labels are being applied too broadly:
   • Should these be temporary labels removed after processing?
   • Are there sub-categories that would be more useful?
   • Should some issues have these labels removed?
3. Propose label taxonomy improvements:
   • Consider plan-* subcategories (e.g., plan-active, plan-completed)
   • Consider retiring overused labels in favor of more specific ones
   • Suggest labels that provide better signal for triage
4. Document label usage guidelines in CONTRIBUTING.md

Files to Modify

• CONTRIBUTING.md - Add label usage guidelines
• GitHub repository settings (if creating/modifying labels)

Acceptance Criteria

• Label distribution analysis completed and documented
• Recommendations provided for label taxonomy improvements
• Label usage guidelines added to CONTRIBUTING.md
• If actionable changes identified, implementation plan provided
• No breaking changes to existing automation that depends on these labels

Estimated Effort

Quick (1-2 hours)
Related to #6857

AI generated by Plan Command for discussion #6855

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

• Fixes [plan] Review and rebalance label distribution #6862

---

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

[pelikhan]

@copilot move to specs/labels.md

[Copilot]

@copilot move to specs/labels.md

Moved to specs/labels.md with references added to CONTRIBUTING.md in commit 50b9a10.