docs: Add Linear SDK async properties guide

[chindris-mihai-alexandru]

Summary

This PR adds comprehensive documentation about async property patterns in the Linear SDK and common performance footguns that occur when using the SDK directly. This guide helps users understand when to use agent2linear versus the SDK, and how to avoid N+1 query problems.

Motivation

While researching Linear API integration patterns, I noticed that the Linear SDK documentation lacks detailed guidance about the performance implications of lazy loading. The SDK's design (where all entity relations return Promises) can lead to severe N+1 query problems if developers aren't aware of this behavior.

This documentation fills that gap by providing practical examples and mitigation strategies.

What's Included

Comprehensive Async Properties Reference

• docs/linear-sdk-gotchas.md - Complete guide to async property patterns
  • Documented async properties for: Issue, Project, Team, WorkflowState, User
  • Clear distinction between async relations and synchronous ID properties
  • Collection methods vs single entity relations

Common Performance Footguns

Four detailed examples with bad and good patterns:

1. The N+1 Query Problem - Accessing relations in loops
2. Checking Existence vs Fetching Data - Using IDs first
3. Repeated Access to Same Property - SDK doesn't cache
4. Collection Iteration - Relations aren't pre-fetched

Mitigation Strategies

Five practical approaches with code examples:

1. Use agent2linear for CLI operations
2. Write custom GraphQL queries for specific needs
3. Check ID properties before fetching relations
4. Batch operations when using SDK directly
5. Implement caching layer for long-running processes

Decision Framework

Clear guidance on when to use each approach:

• agent2linear: CLI tools, one-time queries, AI agents, bulk operations
• SDK with custom GraphQL: Specific fields, custom integrations, full control
• SDK with caching: Long-running processes, servers, webhooks, real-time updates
• Avoid naive SDK: Lists with nested data, iteration over collections

Key Findings

The Core Issue

All entity relations in the Linear SDK use lazy loading:

// Each of these triggers a separate API call
const assignee = await issue.assignee;
const state = await issue.state;
const team = await issue.team;

ID Properties Are Synchronous

// These are synchronous (no API calls)
const assigneeId = issue.assigneeId;
const stateId = issue.stateId;
const teamId = issue.teamId;

N+1 Query Example

// Triggers 41+ API calls for 20 issues
const issues = await client.issues({ first: 20 });
for (const issue of issues.nodes) {
  const assignee = await issue.assignee;  // +20 calls
  const state = await issue.state;        // +20 calls
}

This is the exact pattern documented in PR #4 (Performance Benchmarks), which showed 41x API call increase with the naive SDK approach.

Pattern References

• Linear SDK TypeScript definitions (v69.0.0)
• Linear GraphQL API documentation
• agent2linear comprehensive query approach
• Cyrus caching layer pattern (ceedaragents/cyrus)

Testing

Documentation verified against:

• Linear SDK v69.0.0 type definitions
• Real-world testing with Linear API
• Cross-referenced with performance benchmarks from PR docs: Add Linear API performance benchmarks #4

Impact

• Helps developers avoid common performance pitfalls
• Provides clear guidance on tool selection
• Documents undocumented SDK behavior
• Complements performance benchmarks with explanations
• Reduces likelihood of N+1 queries in user code

Relationship to Other PRs

This PR complements PR #4 (Performance Benchmarks):

• PR docs: Add Linear API performance benchmarks #4 shows the performance impact with numbers
• This PR explains why those numbers exist and how to avoid the issues
• Together, they provide both quantitative data and qualitative understanding.

Note: This is a documentation-only PR with no code changes.

[Copilot]

Pull request overview

This PR adds comprehensive documentation for async property patterns in the Linear SDK, helping developers understand and avoid performance pitfalls when working with the SDK's lazy-loading architecture. The guide provides detailed explanations of async properties across multiple Linear entity types, common N+1 query anti-patterns, and practical mitigation strategies.

Key Changes

• Added docs/linear-sdk-gotchas.md with 357 lines of comprehensive documentation
• Documented async properties for Issue, Project, Team, WorkflowState, and User objects
• Provided four detailed examples of common performance footguns with bad/good pattern comparisons
• Outlined five mitigation strategies including when to use agent2linear vs SDK vs custom GraphQL

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The code example uses a2l without defining it or explaining that it's an alias for agent2linear. While the bash example on line 211 shows a2l issue list, the TypeScript code on line 199 should either use the full agent2linear name for clarity in documentation, or include a brief note explaining that a2l is a shorthand alias. This is especially important since the document is titled "Linear SDK Async Properties Guide" and focuses on SDK usage patterns.

[chindris-mihai-alexandru]

The context of this guide is comparing SDK usage vs agent2linear. Line 211 shows the bash command 'a2l issue list' which is the standard CLI usage. The guide references the main agent2linear documentation where the alias is explained.

[Copilot]

The reference to ./performance/README.md appears to be broken. Based on the repository structure, this file doesn't exist. The PR description mentions "PR #3 (Performance Benchmarks)" but there's no evidence of this documentation file in the codebase. Consider either removing this link, updating it to point to an existing resource, or noting that this documentation is planned for a future PR.

Suggested change

	- [agent2linear Performance Benchmarks](./performance/README.md) - Real-world N+1 query impact
	- agent2linear Performance Benchmarks (planned; documentation will be added in PR #3) - Real-world N+1 query impact

[chindris-mihai-alexandru]

Intentional forward reference. This refers to PR #4 (Performance Benchmarks) which has already been submitted to this repository. The link uses a relative path that will work once both PRs are merged.

[Copilot]

The code should use optional chaining when accessing assignee.name since assignee could potentially be undefined. While the example shows checking for assignee existence with the if (assignee) condition, using optional chaining (assignee?.name) would be more defensive and consistent with the pattern shown in line 124.

[chindris-mihai-alexandru]

The example intentionally shows the explicit 'if (assignee)' check to make the defensive pattern more visible to developers learning about async properties. The explicit check is pedagogically clearer than optional chaining for this educational context.

[Copilot]

The code should use optional chaining when accessing assignee.name for consistency with the pattern shown in line 124. While checking issue.assigneeId first guards against undefined assignee, using optional chaining (assignee?.name) would be more defensive and follow TypeScript best practices.

Suggested change

	console.log(assignee.name);
	console.log(assignee?.name);

[chindris-mihai-alexandru]

The example demonstrates checking 'issue.assigneeId' first (the performance optimization pattern), then explicitly checking the assignee exists. Using 'assignee.name' without optional chaining after an explicit check is valid and shows the pattern clearly.

[Copilot]

The PR description mentions documenting async properties for six object types including "Cycle", but the documentation only covers five types: Issue, Project, Team, WorkflowState, and User. Consider adding a section for the Cycle object to match the stated scope, or update the PR description to accurately reflect the documented objects.

[chindris-mihai-alexandru]

Intentional scope decision to keep the documentation focused on the most commonly used objects. Cycle patterns would largely duplicate the patterns shown for other objects (async team property, async issues() method). The patterns are consistent across all Linear SDK objects.