Issue Linking

Issue linking is fundamental to GuideMode’s ability to track work from discovery through delivery. This guide explains how links are detected, created, and used to power metrics like validation rate and end-to-end lead time.

Overview

GuideMode supports two types of issue links:

Same-provider links - Links between issues in the same tool (e.g., Jira → Jira)
Cross-tool links - Links between issues in different tools (e.g., Notion → GitHub)

Both types enable the connection between discovery research and delivery work that powers DX² metrics.

Link Types

GuideMode uses eight canonical link types to describe relationships between issues:

Link Type	Direction	Purpose	Example
`validates`	Discovery → Feature	Research proved hypothesis, feature created	Spike validates Feature
`invalidates`	Discovery → (closed)	Research disproved hypothesis	Discovery marked invalid
`implements`	Feature → Discovery	Feature implements validated discovery	Feature implements Spike
`blocks`	Issue → Issue	This issue blocks another	Chore blocks Feature
`blocked_by`	Issue → Issue	This issue is blocked by another	Feature blocked by Chore
`relates_to`	Issue ↔ Issue	General relationship	Feature relates to Bug
`duplicates`	Issue → Issue	This issue duplicates another	Bug duplicates Bug
`duplicated_by`	Issue → Issue	This issue is duplicated by another	Bug duplicated by Bug

The Discovery Connection

The validates and implements links are inverse relationships that connect discovery to delivery:

These links enable:

Validation rate - What percentage of discoveries led to features?
End-to-end lead time - Time from discovery creation to production deployment
Research ROI - Connect research investment to delivered value

Link Detection Methods

GuideMode detects issue links through multiple sources, each with different confidence levels:

1. Native Provider Links

Each provider has its own link system that GuideMode syncs:

Jira:

Issue links with types like “Blocks”, “Relates”, “Clones”
Synced via Jira API during issue sync
Link type names mapped to GuideMode types

GitHub:

Native dependencies API (blocked_by / blocking)
Available via REST API: /repos/{owner}/{repo}/issues/{number}/dependencies
Synced via webhooks (issue_dependencies events)

Linear:

Parent/child relationships
Related issue links
Synced during issue sync

Notion:

Relation properties (links to other databases)
URL properties pointing to external issues
Configured via database mapping

2. URL Detection

GuideMode automatically scans issue body text for URLs from supported providers:

Supported URL Patterns:

Provider	URL Pattern	Extracted ID
GitHub	`github.com/{owner}/{repo}/issues/{number}`	`github:owner/repo#123`
Jira	`{site}.atlassian.net/browse/{key}`	`jira:PROJ-123`
Linear	`linear.app/{workspace}/issue/{id}`	`linear:ABC-123`
Notion	`notion.so/{workspace}/{page-id}`	`notion:page-id`

Cross-Tool Linking

Cross-tool links connect issues across different providers, enabling discovery-to-delivery tracking even when research happens in Notion but delivery happens in GitHub.

How It Works

Bidirectional Queries

Once links are resolved, they can be queried from either direction:

From Notion Discovery:
  "What features implement this research?"
  → Query: sourceIssueId = notionPageId, linkType = 'implements'

From GitHub Feature:
  "What discovery validated this feature?"
  → Query: targetIssueId = githubIssueId, linkType = 'validates'
  → Or inverse: sourceIssueId = githubIssueId, linkType = 'implements'

Link Type Mappings

Different providers use different names for link relationships. GuideMode’s link type mappings let you configure how provider-specific names translate to internal types.

Configuration

Navigate to Settings → Integrations → Link Mappings to configure mappings.

┌─────────────────────────────────────────────────────────────────────────┐
│                         LINK TYPE MAPPING                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Provider: Jira                                                          │
│  External Type: "Implements"                                             │
│  Internal Type: validates                                                │
│                                                                          │
│  ─────────────────────────────────────────────────────────────────────  │
│                                                                          │
│  Optional Conditions:                                                    │
│  • Requires Source Type: discovery                                       │
│  • Requires Target Type: feature                                         │
│                                                                          │
│  (Only apply this mapping when source is discovery                       │
│   and target is feature)                                                 │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Example Mappings

Provider	External Type	→	Internal Type	Condition
Jira	”Blocks”	→	`blocks`	Always
Jira	”Implements”	→	`validates`	Source: discovery, Target: feature
Jira	”Relates”	→	`relates_to`	Always
Linear	”Parent”	→	`blocked_by`	Always
GitHub	”blocked_by”	→	`blocked_by`	Always

Conditional Mappings

Conditional mappings let you apply different internal types based on the issue types involved:

Example: Jira "Relates" link

Default behavior:
  "Relates" → relates_to

With conditional mapping:
  "Relates" where source=discovery AND target=feature → validates
  "Relates" where source=feature AND target=discovery → implements
  "Relates" otherwise → relates_to

This is useful when your provider doesn’t have specific link types for discovery validation.

Notion Relation Properties

Notion databases can have relation properties that link to other databases. GuideMode can map these to issue links.

Configuration

In your Notion database mapping, configure deliveryLinks:

{
  deliveryLinks: [
    {
      notionProperty: "Delivery Ticket",      // Property name in Notion
      notionPropertyType: "url",              // "url" or "relation"
      linkType: "validates"                   // Internal link type
    },
    {
      notionProperty: "Related Features",
      notionPropertyType: "relation",
      linkType: "implements"
    }
  ]
}

URL Properties

For URL-type properties, GuideMode parses the URL to detect the provider and issue:

Notion page with URL property "Delivery Ticket":
  Value: "https://github.com/org/repo/issues/42"

  → Creates link:
    • Source: This Notion page
    • Target: GitHub org/repo#42
    • Type: validates

Relation Properties

For relation-type properties, GuideMode creates links to other Notion pages:

Notion page with Relation property "Related Features":
  Value: [Page A, Page B]

  → Creates links:
    • Source: This page → Target: Page A, Type: implements
    • Source: This page → Target: Page B, Type: implements

GitHub Native Dependencies

GitHub has a native dependencies feature that tracks blocking relationships between issues.

API Endpoints

GET /repos/{owner}/{repo}/issues/{number}/dependencies/blocked_by
GET /repos/{owner}/{repo}/issues/{number}/dependencies/blocking

Webhook Events

GuideMode listens for issue_dependencies webhook events:

Event	Action
`blocked_by_added`	Create `blocked_by` link
`blocked_by_removed`	Remove `blocked_by` link
`blocking_added`	Create `blocks` link
`blocking_removed`	Remove `blocks` link

Cross-Repository Dependencies

GitHub dependencies can span repositories within the same organization:

┌────────────────────┐         blocked_by         ┌────────────────────┐
│  org/frontend#42   │ ◄─────────────────────────│   org/backend#15   │
│  "Add user UI"     │                           │  "Add user API"    │
└────────────────────┘                           └────────────────────┘

Cross-Provider Workflow Examples

GuideMode’s cross-tool linking enables dual-track agile workflows where discovery research happens in one tool and delivery work in another. This is a key differentiator for teams using multiple tools.

Notion Discovery + GitHub Delivery

Scenario: Product team researches in Notion, engineers implement in GitHub.

Setup steps:

Connect Notion integration → Settings → Integrations → Notion
Connect GitHub integration → Settings → Integrations → GitHub
Map Notion database with type: discovery
Add GitHub issue URL to Notion page when research is validated

No additional configuration needed - URL detection works automatically.

Notion Discovery + Linear Delivery

Scenario: Design team researches in Notion, product team delivers in Linear.

URL pattern detected: linear.app/{workspace}/issue/{id}

Jira Discovery + GitHub Delivery

Scenario: Product management in Jira, development in GitHub.

Two linking methods:

URL in description (recommended)
- Add GitHub URL to Jira issue description
- GuideMode detects automatically on sync
Jira native links
- Use Jira’s “Link Issue” with external URL
- Configure link type mapping: Jira “Implements” → GuideMode validates

Metrics Across Providers

Cross-provider links power the same metrics as same-provider links:

Metric	What It Measures
Validation Rate	% of discoveries validated into features (across any provider)
Discovery → Production	Time from discovery close to feature deployment
From Discovery %	Delivery work originating from linked discoveries

→ See Workflow Modes for detailed setup guides

Metrics Powered by Links

Issue links enable several key metrics:

Validation Rate

validationRate = (discoveries with validates link) / (total closed discoveries) × 100

Target: 50-70%

A validation rate of 50-70% indicates healthy discovery - not every hypothesis should be proven correct.

End-to-End Lead Time

totalLeadTime = production_deployment_date - discovery_created_date

Requires: validates link from discovery to feature

Tracks the complete journey from initial research to production.

Discovery to Production

discoveryToProduction = production_deployment_date - discovery_closed_date

Requires: validates link connecting discovery to deployed feature

Measures implementation speed after validation.

Research ROI

By connecting discoveries to features, you can track:

Which discoveries led to shipped features
Time invested in validated vs invalidated research
Research-to-production conversion rates

Troubleshooting

Links Not Appearing

Check sync status:

Ensure both source and target issues are synced
Cross-tool links remain “pending” until both sides sync

Check URL format:

URLs must match supported patterns exactly
Private/internal URLs may not be parseable

Check link type mappings:

Verify provider link types are mapped correctly
Check conditional mappings if links appear with wrong types

Wrong Link Types

Review mappings:

Go to Settings → Link Mappings
Check if a mapping exists for the external link type
Verify conditions match expected issue types

Default behavior:

Unknown link types default to relates_to
Add explicit mappings for provider-specific types

Cross-Tool Links Pending

Links stay “pending” when:

Target issue hasn’t been synced yet
Target URL doesn’t match a synced issue
Provider integration isn’t configured

Resolution:

Sync the target provider/repository
Verify the URL in the source issue is correct
Check that URL matches a syncable issue

How It Works - Overall methodology and flows
Discovery Flow - Discovery validation metrics
Delivery Flow - Feature delivery metrics
GitHub Integration - GitHub setup and configuration
Jira Integration - Jira setup and configuration
Notion Integration - Notion setup and configuration

Issue Linking

Overview

Link Types

The Discovery Connection

Link Detection Methods

1. Native Provider Links

2. URL Detection

Cross-Tool Linking

How It Works

Bidirectional Queries

Link Type Mappings

Configuration

Example Mappings

Conditional Mappings

Notion Relation Properties

Configuration

URL Properties

Relation Properties

GitHub Native Dependencies

API Endpoints

Webhook Events

Cross-Repository Dependencies

Cross-Provider Workflow Examples

Notion Discovery + GitHub Delivery

Notion Discovery + Linear Delivery

Jira Discovery + GitHub Delivery

Metrics Across Providers

Metrics Powered by Links

Validation Rate

End-to-End Lead Time

Discovery to Production

Research ROI

Troubleshooting

Links Not Appearing

Wrong Link Types

Cross-Tool Links Pending

Related Documentation