Linear SOP Skill

Purpose

Guide consistent Linear ticket management. Provides evidence templates for the mandatory dev/staging/UAT evidence policy.

When This Skill Applies

• Creating new Linear issues
• Updating ticket status
• Attaching evidence to tickets
• Parsing acceptance criteria
• Working with UUIDs and issue IDs

Linear Operations (Manual Process)

Since Gemini CLI doesn't have native Linear integration, use the Linear web UI or CLI for these operations:

Reading Issues

bash
1# Via Linear Web UI
2# Navigate to: https://linear.app/team/{{PROJECT_TEAM_NAME}}/issue/{{TICKET_PREFIX}}-XXX
3
4# Or use Linear CLI if installed
5linear issue view {{TICKET_PREFIX}}-XXX

Creating Issues

bash
1# Via Linear Web UI: Click "New Issue" or press C
2# Or use Linear CLI:
3linear issue create --title "feat(scope): description" --team {{PROJECT_TEAM_NAME}}

Updating Issues

bash
1# Via Linear Web UI: Open issue and update status
2# Or use Linear CLI:
3linear issue update {{TICKET_PREFIX}}-XXX --state "Done"

Adding Comments

bash
1# Via Linear Web UI: Open issue and add comment
2# Or use Linear CLI:
3linear issue comment {{TICKET_PREFIX}}-XXX "**Dev Evidence**\n\n..."

Evidence Policy (MUST)

Every issue requires evidence at each phase:

Evidence Templates

Dev Evidence Template

markdown
1**Dev Evidence**
2
3**PR**: https://github.com/{{ORG_NAME}}/{{REPO_NAME}}/pull/XXX
4**Commit**: [short-hash]
5**Branch**: {{TICKET_PREFIX}}-XXX-description
6
7**Implementation:**
8
9- [x] Feature implemented
10- [x] Tests passing
11- [x] Lint passing
12
13**Verification:**
14
15\`\`\`bash
16yarn ci:validate
17
18# Output: All checks passed
19
20\`\`\`

Staging/UAT Evidence Template

markdown
1**Staging Evidence**
2
3**Environment**: Pop OS dev server
4**URL**: http://pop-os:3000
5
6**Validation Steps:**
7
81. Deployed to staging: [timestamp]
92. Smoke test passed: [yes/no]
103. Feature verified: [description]
11
12**UAT Status:** [Passed/Pending/N/A]
13
14If N/A, reason: [e.g., "Dev tooling only - no user-facing changes"]

Done Evidence Template

markdown
1**Done Evidence**
2
3**PR Merged**: https://github.com/{{ORG_NAME}}/{{REPO_NAME}}/pull/XXX
4**Merge Commit**: [hash]
5
6**Final Checklist:**
7
8- [x] All acceptance criteria met
9- [x] Documentation updated (if applicable)
10- [x] No regressions detected

Acceptance Criteria Parsing

When reading issue descriptions, extract ACs:

markdown
1## Acceptance Criteria
2
3- [ ] User can perform action X
4- [ ] System responds with Y
5- [ ] Error handling for Z

Convert to testable checklist:

typescript
1const acceptanceCriteria = [
2  { criterion: "User can perform action X", verified: false },
3  { criterion: "System responds with Y", verified: false },
4  { criterion: "Error handling for Z", verified: false },
5];

Status Workflow

text
1Backlog -> Ready -> In Progress -> Testing -> Ready for Review -> Done

GitHub-Linear Auto-Sync

Tickets referenced in commit messages (e.g., [{{TICKET_PREFIX}}-123]) automatically move to Done when the PR merges. Child stories not referenced in any commit message must be manually closed after merge.

Best practice: Reference Feature-level tickets in commit messages. After merge, manually close orphaned child stories that weren't referenced.

Status Update Guidelines

UUID Handling

Linear uses UUIDs internally. When working with APIs:

typescript
1// Issue identifiers (human-readable)
2const issueId = "{{TICKET_PREFIX}}-459";
3
4// UUIDs (API operations)
5const uuid = "ef6a5fa0-2b46-417f-8266-dea2d187b10a";
6
7// Get UUID from identifier via Linear web UI or API
8// The issue URL contains the UUID

Common Operations

Link PR to Issue

PRs are automatically linked when:

• Branch name contains {{TICKET_PREFIX}}-XXX
• PR title contains [{{TICKET_PREFIX}}-XXX]

Create Sub-Issue

Use Linear web UI: Click "Add sub-issue" on parent issue

Query by Label

Use Linear web UI filters:

1. Open team view
2. Click "Filter"
3. Select label (e.g., "sprint-1")

Reference

• Agent Workflow SOP: docs/sop/AGENT_WORKFLOW_SOP.md
• Linear Documentation: https://linear.app/docs
• CONTRIBUTING.md: Workflow documentation