Label Mapping

GuideMode normalizes labels from all connected providers (GitHub, Jira, Linear, Notion) into a consistent set of issue types. This enables unified analytics and metrics across your entire workflow.

Why Label Mapping?

Different teams and tools use different labeling conventions:

• GitHub might use enhancement or feature-request
• Jira might use Story as an issue type
• Linear might use improvement
• Notion might have a custom Type field

GuideMode maps all of these to a canonical set of issue types, enabling consistent metrics like work distribution and type-based filtering.

Issue Types

GuideMode classifies all issues into seven canonical types:

Type	Description	Work Category
feature	New functionality or capability	Planned
bug	Defects or issues to fix	Unplanned
chore	Maintenance and housekeeping	Planned
tech_debt	Technical debt remediation	Unplanned
discovery	Research, spikes, or exploration	Planned
incident	Production incidents or outages	Unplanned
other	Uncategorized issues	-

Mapping Priority

When determining an issue’s type, GuideMode uses a priority-based approach:

Priority Order

1. Custom Mappings (Highest Priority)

   • Repository-specific mappings checked first
   • Global mappings checked second
   • Configured in Settings → Integrations → Label Mappings

2. Standard Label Inference

   • Pattern matching against common label names
   • Case-insensitive partial matching

3. Fallback

   • Returns other if no mapping found

Standard Label Patterns

GuideMode includes built-in patterns for common label conventions:

Issue Type	Matching Patterns
bug	bug, bugfix, defect, fix, hotfix, regression
feature	feature, enhancement, improvement, story
tech_debt	tech-debt, technical-debt, techdebt, debt, legacy, cleanup-debt
chore	chore, refactor, maintenance, cleanup
discovery	spike, research, investigation, discovery, exploration
incident	incident, outage, critical, emergency, p0, p1, sev0, sev1

Pattern matching is:

• Case-insensitive (BUG matches bug)
• Partial matching (bugfix contains bug)
• Priority ordered (tech-debt is checked before chore to avoid false matches)

Examples

Label	Inferred Type	Reason
enhancement	feature	Contains “enhancement”
type:bug	bug	Contains “bug”
tech-debt-cleanup	tech_debt	Contains “tech-debt”
P0	incident	Exact match for severity
documentation	other	No pattern match

Blocked Status Detection

In addition to type mapping, labels can indicate that an issue is blocked:

Default Blocked Patterns

Pattern	Description
blocked	Exact match
on-hold, on hold, onhold	On hold variations
waiting, waiting-for, waiting for	Waiting states
*dependency*	Contains “dependency”
needs-*	Starts with “needs-”
*awaiting*	Contains “awaiting”

Custom Blocked Mappings

When you configure custom blocked mappings in Settings → Integrations → Label Mappings, they completely override the default patterns. This allows teams to:

• Use team-specific terminology
• Disable default blocked detection
• Map labels to blocked that don’t match default patterns

Custom Label Mappings

Configure custom mappings in Settings → Integrations → Label Mappings.

Mapping Fields

Field	Description
externalLabel	The label name from the provider (e.g., “enhancement”)
internalType	The GuideMode type to map to (feature, bug, etc.)
mapsToBlocked	Whether this label indicates blocked status
repositoryId	Optional - scope mapping to specific repository

Scoping

Mappings can be scoped to specific repositories:

1. Repository-specific - Only applies to issues in that repository
2. Global - Applies to all issues from that provider

Repository-specific mappings take priority over global mappings.

Example Configuration

External Label	Internal Type	Blocked	Repository
enhancement	feature	No	Global
improvement	feature	No	Global
spike	discovery	No	Global
blocked-by-external	-	Yes	Global
waiting-on-design	-	Yes	frontend-repo

Provider-Specific Notes

GitHub

GitHub labels are synced directly. Both issue labels and PR labels are processed.

Jira

Jira has both labels and issue types. GuideMode uses:

1. Labels for custom mappings
2. Jira issue type name as fallback (e.g., “Story” → feature, “Bug” → bug)

Linear

Linear labels are synced. Linear’s built-in issue states are handled separately by Status Mapping.

Notion

Notion databases may have:

• A dedicated Type property (single or multi-select)
• Custom label properties

Configure which properties to use in the Notion integration settings.

Related Documentation

• Issues - Issue types and lifecycle
• Status Mapping - Status to state mapping
• Issue Linking - Cross-issue relationships