Status Mapping

GuideMode normalizes status values from all connected providers (GitHub, Jira, Linear, Notion) into a unified workflow model. This enables consistent metrics, WIP tracking, and time-in-status analytics across your entire organization.

Why Status Mapping?

Different tools represent workflow states differently:

• GitHub: Open/Closed states, with optional GitHub Projects v2 columns
• Jira: Custom workflow statuses like “In Progress”, “Code Review”, “QA”
• Linear: State types (unstarted, started, completed) with custom states
• Notion: Database status properties with custom options

GuideMode maps all of these to a canonical model with:

• 9 SubStatus values for fine-grained workflow tracking
• 3 Issue States derived from SubStatus for high-level filtering

The SubStatus Model

SubStatus provides granular workflow state tracking:

SubStatus	Description	State	In WIP?
backlog	Not started, not prioritized	open	No
ready	Ready to start, prioritized	open	No
discovery	Research, spike, or design work	in_progress	Yes
delivery	Active development	in_progress	Yes
review	Code review, testing, QA	in_progress	Yes
blocked	Waiting on external dependency	open	No
parked	Intentionally paused	open	No
done	Completed successfully	closed	No
canceled	Closed without completion	closed	No

Issue States

The three high-level states are derived from SubStatus:

State	Derived From SubStatuses
open	backlog, ready, blocked, parked
in_progress	discovery, delivery, review
closed	done, canceled

State Machine

The full workflow state machine showing all valid transitions:

Key Transitions

From	To	When
backlog → ready	Issue is prioritized for upcoming work
ready → discovery	Research or design phase begins
ready → delivery	Development starts (no discovery needed)
discovery → delivery	Research complete, development begins
delivery → review	Code complete, ready for review/testing
review → done	Review approved, issue complete
Any → blocked	Waiting on external dependency
Any → parked	Intentionally paused
Any → canceled	Closed without completion

Mapping Priority

When mapping provider status to SubStatus, GuideMode uses this priority:

Scope Priority for Custom Mappings

1. Project + Repository specific (highest)
2. Project specific
3. Repository specific
4. Global (lowest)

This allows different projects or repositories to have different status mappings.

Provider Heuristics

GuideMode includes built-in heuristics for common status names:

GitHub

GitHub issues have simple Open/Closed states, but GitHub Projects v2 provides custom column statuses:

Status Pattern	SubStatus
closed:COMPLETED	done
closed:NOT_PLANNED	canceled
closed (default)	done
Backlog, No Status, New	backlog
Todo, To Do, Ready	ready
Spike, Research, Discovery	discovery
In Progress, In Development	delivery
In Review, Code Review, Testing, QA	review
Blocked, Waiting, Awaiting	blocked
On Hold, Parked	parked
Done, Complete, Shipped	done
Canceled, Won't Fix	canceled

Jira

Status Pattern	SubStatus
Backlog, To Do, Open, New	backlog
Ready, Selected for Development	ready
Discovery, Spike, Research, Analysis	discovery
In Progress, Development, Coding	delivery
In Review, Code Review, Testing, QA	review
Blocked, On Hold, Waiting, Pending	blocked
Parked, Deferred, Postponed	parked
Done, Closed, Resolved, Shipped	done
Canceled, Won't Do, Duplicate, Rejected	canceled

Linear

Status Pattern	SubStatus
Backlog, Triage, Unstarted	backlog
Todo, To Do, Ready, Up Next	ready
Discovery, Spike, Research	discovery
In Progress, Started, Doing, Active	delivery
In Review, Review, Testing, QA	review
Blocked, Waiting, On Hold	blocked
Parked	parked
Done, Complete, Completed, Merged	done
Canceled, Duplicate	canceled

Notion

Status Pattern	SubStatus
Not Started, Backlog, New	backlog
To Do, Ready, Planned	ready
Discovery, Research, Exploring	discovery
In Progress, Doing, Active, Working	delivery
Review, In Review, Testing	review
Blocked, On Hold, Waiting	blocked
Parked, Paused	parked
Done, Complete, Finished, Shipped	done
Canceled, Archived, Dropped	canceled

WIP Exclusion

Work In Progress (WIP) metrics only count issues that are actively being worked on:

SubStatus	Included in WIP?	Reason
backlog	No	Not started
ready	No	Waiting to start
discovery	Yes	Active research
delivery	Yes	Active development
review	Yes	Active review/testing
blocked	No	Waiting on dependency
parked	No	Intentionally paused
done	No	Completed
canceled	No	Closed

This ensures WIP metrics accurately reflect work that is actively consuming team capacity.

Timestamps

GuideMode tracks comprehensive timestamps for time-in-status analytics:

Core Timestamps

Timestamp	Description	Set When
createdAt	When issue was created	Initial creation
startedAt	When work began	First transition to in_progress (legacy)
updatedAt	Last modification	Any update
closedAt	When issue was closed	State → closed
firstResponseAt	First comment or review	First engagement

Transition Timestamps

Each SubStatus transition is tracked with a dedicated timestamp:

Timestamp	Description	Triggered By
readyAt	When issue became prioritized	SubStatus → ready
discoveryStartedAt	When research/spike began	SubStatus → discovery
deliveryStartedAt	When active development began	SubStatus → delivery
reviewStartedAt	When entered review/QA	SubStatus → review
blockedAt	When became blocked	SubStatus → blocked
parkedAt	When intentionally paused	SubStatus → parked

Notes:

• backlog has no timestamp (initial state)
• done and canceled use closedAt
• Timestamps are set on transition TO the state, not FROM it

Complete Timestamp Flow

Metrics from Timestamps

These timestamps enable powerful metrics:

Metric	Calculation
Lead Time	closedAt - createdAt
Cycle Time	closedAt - startedAt (or deliveryStartedAt)
Discovery Duration	deliveryStartedAt - discoveryStartedAt
Development Duration	reviewStartedAt - deliveryStartedAt
Review Duration	closedAt - reviewStartedAt
Time to Ready	readyAt - createdAt
Time Blocked	Sum of periods in blocked state

Custom Status Mappings

Configure custom mappings in Settings → Integrations → Status Mappings.

Mapping Fields

Field	Description
externalStatus	The status name from the provider
internalSubStatus	The GuideMode SubStatus to map to
projectId	Optional - scope to specific project
repositoryId	Optional - scope to specific repository

Example Configuration

External Status	SubStatus	Scope
In Development	delivery	Global
Awaiting PR Review	review	Global
Customer Validation	review	frontend-project
Sprint Backlog	ready	mobile-repo

Native Status Preservation

GuideMode stores the original provider status in the nativeStatus field. This allows:

• Debugging mapping issues
• Reconfiguring mappings without data loss
• Provider-specific filtering in advanced queries

Related Documentation

• Issues - Issue states and lifecycle
• Label Mapping - Label to type mapping
• DORA Metrics - Lead time, cycle time calculations
• Delivery Flow - Delivery metrics dashboard