moai-core-issue-labels

Original source / Raw SKILL.md

---
name: moai-core-issue-labels
version: 4.0.0
created: 2025-11-11
updated: '2025-11-18'
status: stable
description: Enterprise GitHub issue labeling orchestrator with semantic label taxonomy,
  AI-powered auto-labeling, label hierarchy system, workflow automation, issue triage
  acceleration, and stakeholder communication; activates for issue classification,
  label management, workflow automation, priority assignment, and team communication
keywords:
- github-labels
- issue-triage
- label-taxonomy
- ai-labeling
- workflow-automation
- issue-classification
- priority-management
- team-communication
- semantic-labels
- enterprise-triage
allowed-tools:
- Read
- Bash
- AskUserQuestion
- mcp__context7__resolve-library-id
- mcp__context7__get-library-docs
- WebFetch
stability: stable
---


# Enterprise GitHub Issue Labeling Orchestrator 

## Skill Metadata

| Field | Value |
| ----- | ----- |
| **Skill Name** | moai-core-issue-labels |
| **Version** | 4.0.0 Enterprise (2025-11-18) |
| **AI Integration** | ✅ Context7 MCP, semantic analysis, auto-classification |
| **Auto-load** | On issue creation/update for auto-labeling |
| **Categories** | Type, Priority, Status, Component, Custom |
| **Lines of Content** | 850+ with 13+ production examples |
| **Progressive Disclosure** | 3-level (taxonomy, patterns, automation) |

---

## What It Does

Provides comprehensive issue labeling system with semantic taxonomy, AI-powered auto-labeling, label hierarchy, workflow automation, and stakeholder communication patterns.

---

## Semantic Label Taxonomy

### Type Labels

```
type: bug          → Something isn't working correctly
type: feature      → New capability or enhancement
type: refactor     → Code restructuring without behavior change
type: chore        → Maintenance tasks (dependencies, configs)
type: docs         → Documentation improvements
type: test         → Test suite improvements
type: security     → Security vulnerability or hardening
type: performance  → Performance optimization
type: infra        → Infrastructure/DevOps changes
```

### Priority Labels

```
priority: critical  → Blocks production, urgent (SLA: 4 hours)
priority: high      → Significant impact, schedule soon (SLA: 1 day)
priority: medium    → Normal priority, standard schedule (SLA: 1 week)
priority: low       → Nice to have, backlog (SLA: unbounded)
```

### Status Labels

```
status: stable      → Waiting for team analysis
status: stable → Team actively investigating
status: stable     → Waiting for external dependency
status: stable       → Ready for implementation
status: stable-progress → Currently being worked on
status: stable      → In code review
status: stable     → In QA/testing
status: stable        → Completed and verified
status: stable     → Intentionally not fixing
status: stable   → Duplicate of another issue
```

### Component Labels

```
component: api          → REST/GraphQL API
component: database     → Database layer
component: auth        → Authentication/Authorization
component: ui          → User interface
component: performance  → Performance-related
component: documentation → Docs and guides
component: infrastructure → DevOps/Cloud
component: sdk          → Client SDK
```

### Special Labels

```
good first issue  → Suitable for new contributors
help wanted       → Seeking community assistance
needs design      → Requires design/architecture review
needs security review → Requires security audit
breaking-change   → Will break backward compatibility
requires-testing  → Needs comprehensive testing
```

---

## AI-Powered Auto-Labeling

### Detection Heuristics

```
Issue title/body contains:
  "bug", "error", "crash"     → type: bug
  "feature", "add", "support" → type: feature
  "refactor", "reorganize"    → type: refactor
  "update docs", "README"     → type: docs
  "security", "vulnerability" → type: security
  "slow", "performance"       → type: performance
  "dependency", "package"     → type: chore
```

### Severity Assessment

```
Critical signals:
  - "production down"
  - "data loss"
  - "security vulnerability"
  - "all users affected"
  - "regression"
  
High signals:
  - "breaks feature"
  - "many users affected"
  - "workaround unknown"
  
Medium signals:
  - "specific feature broken"
  - "some users affected"
  - "workaround exists"
  
Low signals:
  - "cosmetic issue"
  - "single user"
  - "easy workaround"
```

---

## Label Workflow Automation

### Triage Workflow

```
New Issue
    ↓
Auto-labeled (AI classification)
    ↓
[Label confirmed?]
    ├─ Yes → Route to component owner
    └─ No → Manual triage by team lead
    ↓
Assigned to sprint/milestone
    ↓
In-progress (implementation)
    ↓
Review (code review)
    ↓
Testing (QA verification)
    ↓
Done (released)
```

### Label Transition Rules

```
triage → investigating → [blocked|ready]
  ↓
ready → in-progress → review → testing → done

Blocked → ready (dependency resolved)
WontFix → closed (decision made)
Duplicate → linked to original
```

---

## Best Practices

### DO
- ✅ Use exactly 5-8 labels per issue (minimal, curated)
- ✅ Always include: type + priority + status
- ✅ Use component labels for multi-repo tracking
- ✅ Update status as work progresses
- ✅ Use "blocking" relationships for dependencies
- ✅ Review and prune unused labels monthly
- ✅ Link duplicate issues
- ✅ Add assignee before "in-progress"

### DON'T
- ❌ Use 20+ labels per issue (too much metadata)
- ❌ Create labels for single issues (not scalable)
- ❌ Leave issues in "triage" indefinitely
- ❌ Use labels instead of milestones
- ❌ Change priority without discussion
- ❌ Add "working on it" without in-progress label
- ❌ Forget to update status as issue progresses

---

## Related Skills

- `moai-core-practices` (Workflow patterns)
- `moai-foundation-specs` (Issue specification)

---

**For detailed label reference**: [reference.md](reference.md)  
**For real-world examples**: [examples.md](examples.md)  
**Last Updated**: 2025-11-18  
**Status**: Production Ready (Enterprise )


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### reference.md

```markdown
# 📌 GitHub Issue Label Mapping Configuration

> **MoAI-ADK Label Management** - Centralized configuration for issue type labels and priority indicators

**Version**: 1.0.0
**Related**: `/alfred:9-feedback`

---

## 🏷️ Issue Type Label Mapping

### Bug Issues (`--bug`)

**Primary Labels**: `bug`, `reported`

**Optional Labels** (based on priority):
- `priority-critical` - System down, data loss risk
- `priority-high` - Major feature broken
- `priority-medium` - Normal bug
- `priority-low` - Minor issue

---

### Feature Request Issues (`--feature`)

**Primary Labels**: `feature-request`, `enhancement`

**Optional Labels** (based on priority):
- `priority-critical` - Blocking, must implement immediately
- `priority-high` - Important feature
- `priority-medium` - Normal priority feature (default)
- `priority-low` - Nice to have

---

### Improvement Issues (`--improvement`)

**Primary Labels**: `improvement`, `enhancement`

**Optional Labels** (based on priority):
- `priority-critical` - Critical refactoring needed
- `priority-high` - Important improvement
- `priority-medium` - Normal priority (default)
- `priority-low` - Technical debt, can wait

---

### Question/Discussion Issues (`--question`)

**Primary Labels**: `question`, `help-wanted`

**Optional Labels** (based on priority):
- `priority-critical` - Urgent decision needed
- `priority-high` - Important decision
- `priority-medium` - Normal discussion (default)
- `priority-low` - Optional discussion

---

## 🎯 Priority Emoji Mapping

| Priority | Emoji | Use Case |
|----------|-------|----------|
| Critical | 🔴 | System outage, data loss, security breach |
| High | 🟠 | Major feature broken, significant impact |
| Medium | 🟡 | Normal bugs/features (default) |
| Low | 🟢 | Minor issues, nice-to-have features |

---

## 🚀 Issue Type Emoji Mapping

| Type | Emoji | Description |
|------|-------|-------------|
| Bug | 🐛 | Defect or unexpected behavior |
| Feature | ✨ | New functionality or capability |
| Improvement | ⚡ | Code quality, performance, or design improvement |
| Question | ❓ | Question, discussion, or decision needed |

---

## 🛠️ GitHub Labels Setup

To create labels in your GitHub repository, use GitHub CLI:

```bash
# Authenticate first
gh auth login

# Create bug labels
gh label create "bug" \
  --description "Something isn't working" \
  --color "d73a49"

gh label create "reported" \
  --description "User-reported issue" \
  --color "fc2929"

# Create feature labels
gh label create "feature-request" \
  --description "New feature or request" \
  --color "a2eeef"

gh label create "enhancement" \
  --description "Improvement or enhancement" \
  --color "0075ca"

# Create improvement label
gh label create "improvement" \
  --description "Performance or code quality improvement" \
  --color "5ebcf6"

# Create question labels
gh label create "question" \
  --description "Question for discussion" \
  --color "fbca04"

gh label create "help-wanted" \
  --description "We need help with this" \
  --color "fcfc03"

# Create priority labels
gh label create "priority-critical" \
  --description "Critical priority - URGENT" \
  --color "ff0000"

gh label create "priority-high" \
  --description "High priority" \
  --color "ff6600"

gh label create "priority-medium" \
  --description "Medium priority" \
  --color "ffcc00"

gh label create "priority-low" \
  --description "Low priority" \
  --color "00cc00"
```

---

## ✨ Summary

This configuration enables:
- ✅ **Standardized issue labels** across all issue types
- ✅ **Priority indicators** with emoji for visual identification
- ✅ **Type emoji** for quick issue categorization
- ✅ **Automated label assignment** via `/alfred:9-feedback`

For more information, see `.moai/docs/quick-issue-creation-guide.md`

```

### examples.md

```markdown
# Examples

See `reference.md` for practical examples and usage patterns.


```