Update Linear Issue

Update Linear issues with debugging findings, status changes, and investigation notes.

When to Use

• Adding debugging findings as comments
• Updating issue status after investigation
• Adding labels for categorization
• Changing priority based on severity
• Recording root cause analysis

Pre-flight Checks

Authentication

# Check linearis is available and authenticated
linearis --version 2>/dev/null || {
  echo "linearis CLI not installed"
  exit 1
}

linearis issues list --limit 1 >/dev/null 2>&1 || {
  echo "Not authenticated to Linear"
  exit 1
}

Common Commands

1. Add Comment

# Add single-line comment
linearis comments create ENG-1234 --body "Root cause identified: database connection pool exhausted"

# Add multi-line comment with heredoc
linearis comments create ENG-1234 --body "$(cat <<'EOF'
## Investigation Findings

**Root Cause**: Database connection pool exhausted

**Evidence**:
- GCP logs show "connection refused" errors starting at 10:30 UTC
- Kubernetes events show 1/3 pods in CrashLoopBackOff
- Pod describe shows max_connections reached

**Timeline**:
- 10:28 UTC: Traffic spike to 3x normal
- 10:30 UTC: First connection errors
- 10:32 UTC: Pod restarts begin

**Recommendation**: Increase database connection pool limit from 100 to 250
EOF
)"

2. Update Issue Status

# Change state to "In Progress"
linearis issues update ENG-1234 --state "In Progress"

# Change state to "Done"
linearis issues update ENG-1234 --state "Done"

# Common states: "Backlog", "Todo", "In Progress", "In Review", "Done", "Canceled"

3. Update Priority

# Set priority (1 = Urgent, 2 = High, 3 = Medium, 4 = Low)
linearis issues update ENG-1234 --priority 1

# Lower priority after resolution
linearis issues update ENG-1234 --priority 4

4. Add Labels

# Add labels (comma-separated)
linearis issues update ENG-1234 --labels "bug,production,database"

# Add labels (adding mode - default)
linearis issues update ENG-1234 --labels "investigating" --label-by adding

# Replace all labels (overwriting mode)
linearis issues update ENG-1234 --labels "resolved,production" --label-by overwriting

# Clear all labels
linearis issues update ENG-1234 --clear-labels

5. Update Multiple Fields

# Update status, priority, and add comment in sequence
linearis issues update ENG-1234 \
  --state "In Progress" \
  --priority 2 \
  --labels "investigating,production"

linearis comments create ENG-1234 --body "Started investigation - checking GCP logs and K8s events"

6. Update Title or Description

# Update title
linearis issues update ENG-1234 --title "API Gateway connection pool exhaustion in production"

# Update description
linearis issues update ENG-1234 --description "$(cat <<'EOF'
Production issue: API gateway pods crashing due to database connection pool exhaustion.

Impact: 30% of requests failing
Started: 2025-12-24 10:28 UTC
Environment: production (example-production project)
EOF
)"

Output Management

Log updates for audit trail:

# Log comment creation
linearis comments create ENG-1234 --body "Investigation complete" | tee -a /tmp/linear-updates-$(date +%Y%m%d).log

# Log status updates
echo "[$(date)] Updated ENG-1234 to 'Done'" >> /tmp/linear-updates.log
linearis issues update ENG-1234 --state "Done"

Workflow Pattern

Complete debugging → Linear update workflow:

# 1. Read issue for context
linearis issues read ENG-1234 > /tmp/issue-ENG-1234.json

# 2. Debug (using platform debugging skills)
# ... debugging steps ...

# 3. Add findings to issue
linearis comments create ENG-1234 --body "$(cat <<'EOF'
## Root Cause Analysis

Found database connection pool exhaustion.

See attached logs:
- GCP logs: /tmp/gcp-errors-20251224.json
- K8s events: /tmp/k8s-events-20251224.txt
EOF
)"

# 4. Update status
linearis issues update ENG-1234 \
  --state "In Progress" \
  --labels "root-cause-identified"

# 5. After fix is deployed
linearis comments create ENG-1234 --body "Fix deployed, monitoring for 24h"
linearis issues update ENG-1234 --state "Done"

Tips

• Use heredoc for multi-line comments with formatting
• Include timestamps in comments for timeline clarity
• Reference log files saved to /tmp in comments
• Update status incrementally (Backlog → In Progress → Done)
• Add labels for categorization and filtering
• Priority 1 (Urgent) should be reserved for production incidents
• Use --body with heredoc to preserve markdown formatting in comments
• Save comment text to /tmp first if very long, then reference file