skills/project-skills-setup/issue-tracker.md

Issue tracker: Linear

Issues and specs for this repository live in the {{WORKSPACE_NAME}} Linear workspace, under the {{TEAM_NAME}} team ({{TEAM_KEY}}){{PROJECT_SENTENCE}}. Use the authenticated official Linear MCP server for all operations. Do not infer the tracker from the Git remote.

Conventions

• Create and update issues with save_issue; use team {{TEAM_NAME}}{{PROJECT_ARGUMENT}} and state {{OPEN_STATE}} unless another state is explicitly required.
• Read one issue with get_issue, including relations when blockers matter. Read its discussion with list_comments.
• List issues with list_issues, scoped to team {{TEAM_NAME}}{{PROJECT_ARGUMENT}}.
• Add resolution or progress comments with save_comment.
• Apply labels with save_issue; create missing Wayfinder labels with save_issue_label, scoped to the {{TEAM_NAME}} team.
• Treat state {{DONE_STATE}} as closed/resolved and {{CANCELED_STATE}} as ruled out of scope. Other states are open.
• In human-facing text, refer to an issue by its linked title, not only its identifier.

When a skill says “publish to the issue tracker”

Create a Linear issue in team {{TEAM_NAME}}{{PROJECT_ARGUMENT}}.

When a skill says “fetch the relevant ticket”

Resolve its URL, UUID, identifier, or title with get_issue; include comments or relations when the workflow needs them.

Wayfinding operations

• Map: a {{OPEN_STATE}} issue labelled wayfinder:map, containing Destination, Notes, Decisions so far, Not yet specified, and Out of scope.
• Child ticket: a {{OPEN_STATE}} sub-issue whose parentId is the map. Apply exactly one type label: wayfinder:research, wayfinder:prototype, wayfinder:grilling, or wayfinder:task.
• Blocking: use Linear’s native issue relation by adding blocker identifiers through blockedBy. Never encode a blocker only in prose.
• Frontier: list the map’s children, exclude completed and canceled states, exclude assigned issues, then inspect relations and exclude issues with an open blocker. Choose the earliest-created remaining child.
• Claim: assign the ticket to me with save_issue before any investigation or discussion. Assignment alone is the claim.
• Resolve: add the answer with save_comment, set the ticket to {{DONE_STATE}}, then add a one-line linked gist to the map’s Decisions-so-far section with an atomic description patch.
• Rule out of scope: comment with the scope reason, set the ticket to {{CANCELED_STATE}}, and add a linked one-line gist under the map’s Out of scope section. Do not add it to Decisions so far.
• Labels: maintain team-scoped labels wayfinder:map, wayfinder:research, wayfinder:prototype, wayfinder:grilling, and wayfinder:task.