Read Linear Work Item: $ARGUMENTS
Fetch the full scope of the item AND its related graph. Downstream agents must never act on an item in isolation — always call this skill first so they see blockers, project siblings, linked PRs, and historical comments.
This skill is the destination of the lisa-tracker-read shim when tracker = "linear". Read-only.
Repository name for scoped comments and logs: basename $(git rev-parse --show-toplevel).
Configuration
Reads linear.workspace, linear.teamKey from .lisa.config.json (with .local override).
Phase 1 — Resolve Context
- If
$ARGUMENTS matches <TEAM>-<n> → Issue mode.
- If
$ARGUMENTS is a URL containing /project/<slug>-<short-id> → Project mode (extract <short-id>).
- Otherwise stop and report. Do NOT guess.
- Resolve team ID via
lisa-linear-access operation: list-teams({query: <teamKey>}).
Phase 2 — Fetch Primary Item
Issue mode
Call lisa-linear-access operation: get-issue. Extract and preserve:
Metadata
- Identifier, title, issue type (typically a label or workflow state), state, priority (0–4)
- Assignee, creator, subscribers
- Labels (capture full names —
status:*, component:*, priority:*, prd-*)
- Project (parent), parent Issue (if Sub-task), cycle, milestone (ProjectMilestone)
- Estimate, due date
- Created, updated, completed dates
Body
- Full description (preserve markdown)
- Validation Journey section if present (pass verbatim to downstream)
- Attachment URLs (capture, do not download unless needed)
Comments
Fetch ALL comments via lisa-linear-access operation: list-comments({issueId: <id>}) in chronological order. Page to exhaustion: request the next page while pageInfo.hasNextPage is true, passing endCursor as after, and never stop at the first page. Walk thread parents/children — Linear comments are threaded via parentId. Do not truncate. Linear reports no comment total, so <total> is the fetched count once hasNextPage is false, and unknown when a page fails — in which case set comments_complete: false and say so at the top of the Comments section. For each comment:
- Author, timestamp, body
- Flag comments that contain: credentials, reproduction steps, status updates from stakeholders, decisions, or triage headers.
Project mode
Call lisa-linear-access operation: get-project with includeMilestones: true, includeResources: true. Extract:
Metadata
- ID, slug, name, state, priority, lead, color
- Teams, labels, milestones, target date, start date
- Created, updated dates
Body
- Description (markdown)
- Attached documents — call
lisa-linear-access operation: list-documents({projectId}) then lisa-linear-access operation: get-document per result. Treat each as additional spec content.
Member Issues
- Call
lisa-linear-access operation: list-issues({project: <id>}) to enumerate the Project's Issues. Capture identifier, title, state, parent Issue (for sub-Issue tree).
Phase 3 — Fetch Attachments / Remote Links
Linear stores remote URLs as attachments on the Issue. For each:
- GitHub PR or commit: run
gh pr view <url> --json title,state,body,mergedAt,reviewDecision,comments,reviews (PRs) or gh api repos/<owner>/<repo>/commits/<sha> (commits). Capture title, state, unresolved review comments, merge status.
- Confluence page: capture title and URL. Do not fetch body unless a downstream task explicitly needs it.
- Dashboard / log link / external URL: capture title and URL only.
If gh is not authenticated, note "gh auth required" and continue — do not abort.
Phase 4 — Fetch Relations
Linear native Issue relations are returned in the get_issue response under relations. Group by type:
blocks / blocked_by
relates_to
duplicates / duplicated_by
For each related Issue, call lisa-linear-access operation: get-issue and capture:
- Identifier, title, state, priority, assignee
- Description (full, unless cancelled — then summary only)
- Acceptance Criteria section
- Last 10 comments (chronological)
- Attachments (URLs only — skip deep PR fetch unless the relation is
blocks or blocked_by)
Special handling for blocked_by: fetch full PR details via gh for each blocker's GitHub attachments so the agent knows whether the blocker is actually shipped.
For Project-level relationships (Project ↔ Project), Linear doesn't model native relations — check the Project description and resources for cross-references and capture them as plain links.
Phase 5 — Fetch Project Context
If the primary Item is an Issue with a Project parent:
- Fetch the Project via
lisa-linear-access operation: get-project — full description, milestones, labels, lead.
- Fetch Project documents (Phase 2 procedure).
- Find Project siblings via
lisa-linear-access operation: list-issues({project: <projectId>}) excluding the primary identifier.
- For each sibling, capture: identifier, title, state, priority, assignee, summary (first paragraph of description).
- If a sibling is
Started or In Review with a different assignee, flag it prominently.
If the primary Item IS a Project, Phase 5 is the same as fetching all member Issues (already done in Phase 2 Project mode).
Phase 6 — Fetch Sub-Issues
If the primary Issue has children (sub-Issues), fetch each via lisa-linear-access operation: get-issue: identifier, title, state, assignee, description (first paragraph), Acceptance Criteria.
Phase 7 — Assemble Context Bundle
Produce a single structured output the caller can pass verbatim to downstream agents.
# Linear Work Item Context: <IDENTIFIER>
## Primary Item
- Identifier: <ID>
- Type: <Issue | Project>
- State: <state>
- Priority: <0–4 or named>
- Assignee: <name or none>
- Project (parent): <project-slug — name> or none
- Parent Issue: <ID — title> or none (Sub-task only)
- Cycle: <name or none>
- Milestone: <project-milestone or none>
- Labels: <comma-separated>
- Estimate: <points>
### Description
<full description>
### Acceptance Criteria
<criteria>
### Validation Journey
<section or "None">
### Comments (<fetched> of <total>; comments_complete: <true|false>)
<when incomplete: "INCOMPLETE — <fetched> of <total> comments read via <substrate>">
<chronological comments, flagged items called out>
### Attachments
<list of URLs with titles>
## Remote Links
### Pull Requests (<count>)
- <url> — <title> — <state> — <reviewDecision>
<body summary + unresolved review comments>
### Confluence
- <title> — <url>
### Other
- <title> — <url>
## Relations
### Blocks (<count>)
<per-issue block>
### Blocked By (<count>)
<per-issue block with PR state>
### Relates To (<count>)
<per-issue block>
### Duplicates / Duplicated By
<per-issue block>
## Project Context (when primary is an Issue under a Project)
### Project <slug> — <name>
- State: <state>
- Description: <full markdown>
- Milestones: <list>
- Documents: <list of doc titles + identifiers>
### Siblings In-Flight (<count>)
- <ID> — <state> — <assignee> — <title> **[FLAG: in progress by other assignee]**
### Other Siblings (<count>)
- <ID> — <state> — <title>
## Sub-Issues (<count>)
- <ID> — <state> — <assignee> — <title>
## Summary for Downstream
- Full item count pulled: <N>
- Blockers still open: <list>
- Related in-flight work: <list>
- Relevant PRs: <list with state>
Rules
- Never summarize or truncate the primary item's description or Validation Journey.
- Never skip a relation type, even if it seems unrelated — the downstream agent decides relevance.
- If a related item returns an access error, capture the error and continue. Do not abort the read.
- Flag in-flight sibling work prominently so the caller can avoid duplicate implementation.
- If the Issue has no Project parent, state this explicitly — do not silently skip Phase 5.
- Output is pure context. This skill never modifies the item.
1---2name: lisa-linear-read-issue-33description: "Fetches the full scope of a Linear work item — Issue or Project — including metadata, description, acceptance criteria, all comments, attachments, native relations (blocks/blocked_by/relates_to/duplicates), Project parent (if any) with siblings, and sub-Issues. Produces a consolidated context bundle that downstream agents consume so they never act on a single item in isolation."4allowed-tools: ["Bash", "Skill"]5metadata:6 source: https://skillmd.com/skills/codyswanngt/lisa-linear-read-issue-37---89# Read Linear Work Item: $ARGUMENTS1011Fetch the full scope of the item AND its related graph. Downstream agents must never act on an item in isolation — always call this skill first so they see blockers, project siblings, linked PRs, and historical comments.1213This skill is the destination of the `lisa-tracker-read` shim when `tracker = "linear"`. Read-only.1415Repository name for scoped comments and logs: `basename $(git rev-parse --show-toplevel)`.1617## Configuration1819Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).2021## Phase 1 — Resolve Context22231. If `$ARGUMENTS` matches `<TEAM>-<n>` → Issue mode.242. If `$ARGUMENTS` is a URL containing `/project/<slug>-<short-id>` → Project mode (extract `<short-id>`).253. Otherwise stop and report. Do NOT guess.264. Resolve team ID via `lisa-linear-access operation: list-teams({query: <teamKey>})`.2728## Phase 2 — Fetch Primary Item2930### Issue mode3132Call `lisa-linear-access operation: get-issue`. Extract and preserve:3334**Metadata**35- Identifier, title, issue type (typically a label or workflow state), state, priority (0–4)36- Assignee, creator, subscribers37- Labels (capture full names — `status:*`, `component:*`, `priority:*`, `prd-*`)38- Project (parent), parent Issue (if Sub-task), cycle, milestone (ProjectMilestone)39- Estimate, due date40- Created, updated, completed dates4142**Body**43- Full description (preserve markdown)44- **Validation Journey** section if present (pass verbatim to downstream)45- Attachment URLs (capture, do not download unless needed)4647**Comments**48Fetch ALL comments via `lisa-linear-access operation: list-comments({issueId: <id>})` in chronological order. Page to exhaustion: request the next page while `pageInfo.hasNextPage` is true, passing `endCursor` as `after`, and never stop at the first page. Walk thread parents/children — Linear comments are threaded via `parentId`. Do not truncate. Linear reports no comment total, so `<total>` is the fetched count once `hasNextPage` is false, and `unknown` when a page fails — in which case set `comments_complete: false` and say so at the top of the Comments section. For each comment:49- Author, timestamp, body50- Flag comments that contain: credentials, reproduction steps, status updates from stakeholders, decisions, or triage headers.5152### Project mode5354Call `lisa-linear-access operation: get-project` with `includeMilestones: true`, `includeResources: true`. Extract:5556**Metadata**57- ID, slug, name, state, priority, lead, color58- Teams, labels, milestones, target date, start date59- Created, updated dates6061**Body**62- Description (markdown)63- Attached documents — call `lisa-linear-access operation: list-documents({projectId})` then `lisa-linear-access operation: get-document` per result. Treat each as additional spec content.6465**Member Issues**66- Call `lisa-linear-access operation: list-issues({project: <id>})` to enumerate the Project's Issues. Capture identifier, title, state, parent Issue (for sub-Issue tree).6768## Phase 3 — Fetch Attachments / Remote Links6970Linear stores remote URLs as attachments on the Issue. For each:7172- **GitHub PR or commit**: run `gh pr view <url> --json title,state,body,mergedAt,reviewDecision,comments,reviews` (PRs) or `gh api repos/<owner>/<repo>/commits/<sha>` (commits). Capture title, state, unresolved review comments, merge status.73- **Confluence page**: capture title and URL. Do not fetch body unless a downstream task explicitly needs it.74- **Dashboard / log link / external URL**: capture title and URL only.7576If `gh` is not authenticated, note "gh auth required" and continue — do not abort.7778## Phase 4 — Fetch Relations7980Linear native Issue relations are returned in the `get_issue` response under `relations`. Group by type:8182- `blocks` / `blocked_by`83- `relates_to`84- `duplicates` / `duplicated_by`8586For each related Issue, call `lisa-linear-access operation: get-issue` and capture:87- Identifier, title, state, priority, assignee88- Description (full, unless cancelled — then summary only)89- Acceptance Criteria section90- Last 10 comments (chronological)91- Attachments (URLs only — skip deep PR fetch unless the relation is `blocks` or `blocked_by`)9293**Special handling for `blocked_by`:** fetch full PR details via `gh` for each blocker's GitHub attachments so the agent knows whether the blocker is actually shipped.9495For Project-level relationships (Project ↔ Project), Linear doesn't model native relations — check the Project description and resources for cross-references and capture them as plain links.9697## Phase 5 — Fetch Project Context9899If the primary Item is an Issue with a Project parent:1001011. Fetch the Project via `lisa-linear-access operation: get-project` — full description, milestones, labels, lead.1022. Fetch Project documents (Phase 2 procedure).1033. Find Project siblings via `lisa-linear-access operation: list-issues({project: <projectId>})` excluding the primary identifier.1044. For each sibling, capture: identifier, title, state, priority, assignee, summary (first paragraph of description).1055. If a sibling is `Started` or `In Review` with a different assignee, flag it prominently.106107If the primary Item IS a Project, Phase 5 is the same as fetching all member Issues (already done in Phase 2 Project mode).108109## Phase 6 — Fetch Sub-Issues110111If the primary Issue has children (sub-Issues), fetch each via `lisa-linear-access operation: get-issue`: identifier, title, state, assignee, description (first paragraph), Acceptance Criteria.112113## Phase 7 — Assemble Context Bundle114115Produce a single structured output the caller can pass verbatim to downstream agents.116117```text118# Linear Work Item Context: <IDENTIFIER>119120## Primary Item121- Identifier: <ID>122- Type: <Issue | Project>123- State: <state>124- Priority: <0–4 or named>125- Assignee: <name or none>126- Project (parent): <project-slug — name> or none127- Parent Issue: <ID — title> or none (Sub-task only)128- Cycle: <name or none>129- Milestone: <project-milestone or none>130- Labels: <comma-separated>131- Estimate: <points>132133### Description134<full description>135136### Acceptance Criteria137<criteria>138139### Validation Journey140<section or "None">141142### Comments (<fetched> of <total>; comments_complete: <true|false>)143<when incomplete: "INCOMPLETE — <fetched> of <total> comments read via <substrate>">144<chronological comments, flagged items called out>145146### Attachments147<list of URLs with titles>148149## Remote Links150### Pull Requests (<count>)151- <url> — <title> — <state> — <reviewDecision>152 <body summary + unresolved review comments>153154### Confluence155- <title> — <url>156157### Other158- <title> — <url>159160## Relations161### Blocks (<count>)162<per-issue block>163164### Blocked By (<count>)165<per-issue block with PR state>166167### Relates To (<count>)168<per-issue block>169170### Duplicates / Duplicated By171<per-issue block>172173## Project Context (when primary is an Issue under a Project)174### Project <slug> — <name>175- State: <state>176- Description: <full markdown>177- Milestones: <list>178- Documents: <list of doc titles + identifiers>179180### Siblings In-Flight (<count>)181- <ID> — <state> — <assignee> — <title> **[FLAG: in progress by other assignee]**182183### Other Siblings (<count>)184- <ID> — <state> — <title>185186## Sub-Issues (<count>)187- <ID> — <state> — <assignee> — <title>188189## Summary for Downstream190- Full item count pulled: <N>191- Blockers still open: <list>192- Related in-flight work: <list>193- Relevant PRs: <list with state>194```195196## Rules197198- Never summarize or truncate the primary item's description or Validation Journey.199- Never skip a relation type, even if it seems unrelated — the downstream agent decides relevance.200- If a related item returns an access error, capture the error and continue. Do not abort the read.201- Flag in-flight sibling work prominently so the caller can avoid duplicate implementation.202- If the Issue has no Project parent, state this explicitly — do not silently skip Phase 5.203- Output is pure context. This skill never modifies the item.