# Lisa Linear Write Issue > Creates or updates a Linear work item — Project (Epic), Issue (Story), or sub-Issue (Sub-task) — following organizational best practices. Polymorphic: dispatches internally on issue_type to save_project (Epic) or save_issue (Story / Sub-task). Enforces description quality (three audiences), Gherkin acceptance criteria, project-as-parent for Stories, parentId for Sub-tasks, explicit relationship discovery (blocks / is blocked by / relates to / duplicates), labels, components-as-labels, project milestones for fix versions, native priority and estimate fields, and Validation Journey. Rejects thin items — use this skill any time a Linear work item is created or significantly edited. - Skill: `codyswanngt/lisa-linear-write-issue` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add codyswanngt/lisa-linear-write-issue` - Raw SKILL.md: https://api.skillmd.com/api/skills/codyswanngt/lisa-linear-write-issue/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: codyswanngt (https://skillmd.com/u/codyswanngt) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/codyswanngt/lisa-linear-write-issue --- # Write Linear Work Item: $ARGUMENTS Create or update a Linear work item — Project (for Epics), Issue (for Stories), or sub-Issue (for Sub-tasks) — with all required relationships, metadata, and quality gates. Every section below is mandatory. Thin items are rejected. Repository name for scoped comments: `basename $(git rev-parse --show-toplevel)`. ## Configuration This skill reads configuration from `.lisa.config.json` (with `.lisa.config.local.json` overriding per key). Required keys: - `linear.workspace` — Linear workspace slug - `linear.teamKey` — Linear team key (e.g. `ENG`); the team owns the destination items If either is missing, stop and report — never invent values. ## Polymorphic dispatch Linear's data model maps Epic / Story / Sub-task to **different entity types**. This skill dispatches on `issue_type`: | `issue_type` | Linear entity | MCP write tool | Parent field | |--------------|---------------|----------------|--------------| | `Epic` | **Project** | `lisa-linear-access operation: save-project` | (none — Projects are top-level within a team) | | `Story` / `Task` / `Improvement` | **Issue** | `lisa-linear-access operation: save-issue` | `projectId` (the Epic Project) | | `Sub-task` | **sub-Issue** | `lisa-linear-access operation: save-issue` | `parentId` (the Story Issue) | | `Bug` | **Issue** | `lisa-linear-access operation: save-issue` | `projectId` if part of an Epic; else top-level | | `Spike` | **Issue** | `lisa-linear-access operation: save-issue` | `projectId` if part of an Epic; else top-level | The build lifecycle uses native **workflow states** (`Ready`, `In Progress`, `Blocked`, `On Dev`, `On Stg`, `Done`, plus an optional review state a project may bind), resolved per role from `linear.workflow` — see "Why Linear uses states, not labels" in `config-resolution`. A new **leaf** work unit is created in the configured `ready` state only on explicit `build_ready: true`; omitted or `false` leaves it in the team's default backlog state, and a container is never put in `ready` at all (see the Build-ready control input below). ## Writing by another path? The gates still apply A team that talks to its tracker through its own script is doing a normal thing — the script usually owns the credential plumbing, and Lisa neither controls nor wants to control it. What that script does NOT get is either half of this skill's quality gate, and nothing about the write says so. **A read-back is not the missing check.** A bespoke path almost always re-reads the issue after writing and confirms the tracker stored what was sent. That is worth doing and it is not this. It proves TRANSPORT: the API accepted the payload and the field values round-tripped. It cannot fail for the reason these gates exist, because it never looks at whether what was sent was any good — a issue with no acceptance criteria, no parent, and a human decision left sitting in the middle of it round-trips perfectly. That is the dangerous half of the shape: a failing control gets investigated, a misread one gets trusted. So a write by any other path still owes both phases, and both run standalone against an item that already exists: | Phase | Skill | What it costs you | |---|---|---| | Pre-write validate | `lisa-linear-validate-issue` | Run it on the draft before you send it | | Post-write verify | `lisa-linear-verify` | Run it on the live issue after you send it | ```text Skill(lisa-linear-validate-issue) with the draft issue, or with a reference to a live one Skill(lisa-linear-verify) with ENG-1234 ``` **These are plugin-resident skills invoked through the Skill tool.** They are not shell scripts and will not appear in any repository's `scripts/` directory, including yours. An agent that searches the repo it is standing in, finds nothing, and concludes the capability is absent has made the one mistake that turns a local script from the convenient option into the only one. ## Phase 1 — Resolve Intent Determine from `$ARGUMENTS` and context whether this is a CREATE or UPDATE: - **CREATE**: no existing identifier provided. - **UPDATE**: identifier provided (`-` for Issue, project slug + short-id for Project) — call `/linear-read-issue ` first to load the full current state. Never overwrite without reading. Resolve the team ID for `linear.teamKey` via `lisa-linear-access operation: list-teams({query: })`. Cache it. ## Phase 2 — Gather Required Inputs Required fields (stop and ask if missing — never invent values): | Field | Required For | Notes | |-------|--------------|-------| | `team_key` | CREATE | From `linear.teamKey` config; required for both Project and Issue creation | | `issue_type` | CREATE | One of: Epic, Story, Task, Bug, Spike, Sub-task, Improvement | | Summary | CREATE, UPDATE | One line, imperative voice, under 100 chars | | Description | CREATE, UPDATE | Multi-section markdown — see Phase 3 | | Project parent (for Story / Task / Bug / Spike / Improvement when part of an Epic) | non-Epic, non-Sub-task in Epic context | Linear Project ID — the Epic | | Sub-task parent | Sub-task | Linear Issue ID — the Story | | Priority | CREATE | Native Linear priority: 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low | | Acceptance criteria | Story, Task, Bug, Sub-task, Improvement | Gherkin — see Phase 3 | | Validation Journey | Runtime-behavior changes | Delegate to `/linear-add-journey` | | Target backend environment | Runtime-behavior changes | For every work type, use an exact `deploy.branches` key when an environment is known. Human: bare key or `Confirmed: `. Automation: `Inferred: — evidence: `, `Assumption: — remote default branch ` for a unique reverse-map, or `Assumption: remote default branch ` otherwise. Human confirmation replaces an automated annotation with the bare key or `Confirmed: `. | | Sign-in account / credentials | Items that touch authenticated surfaces | Name the account (or source — 1Password item, env var, seeded fixture) and role; recorded in description. Omit when sign-in is not required. | | Single-repo scope | Bug, Task, Sub-task | These types MUST cover one repo only. If the work crosses repos, split it before creating. Epic / Spike / Story may span repos. | | Source Requirement | PRD-sourced Issues (`prd_source` provided) | `## Source Requirement` with PRD link + verbatim requirement quote(s) — see Phase 3; enforced at every level, sub-issues included. | Optional but recommended: assignee, estimate (story points), labels, project milestone (fix-version equivalent), cycle. ## Phase 3 — Description Quality Linear descriptions are markdown (NOT Jira wiki markup — no `h2.` headings, use `##` instead). The description MUST address three audiences. Reject and rewrite if any are missing. ```markdown ## Source Requirement [Required whenever the Issue originates from a PRD (the caller passes `prd_source`). Answers "why was this done?" — cite the PRD and quote the requirement(s) VERBATIM, never paraphrased: - **PRD**: §"
" - **Requirement (R3)**: "" One Requirement line per satisfied requirement. Derived / cross-cutting work that traces to no single requirement uses the supporting form: "Derived work supporting R3, R7 — no single PRD section." Close with: "This Issue exists to satisfy the quoted requirement. If implementation scope drifts from the quoted text, the PRD is the authority — raise the conflict rather than silently reinterpreting it." Omit the section only for ad-hoc Issues with no PRD lineage.] ## Context / Business Value [Why this matters. Stakeholder-facing. Concrete user impact or business outcome. Link to the originating Slack thread, Notion doc, incident, or customer report.] ## Technical Approach [Developer-facing. Integration points, impacted modules, data model implications, relevant tradeoffs. Not a full design doc — a pointer for someone picking it up.] ## Acceptance Criteria 1. Given When Then 2. Given When Then ## Out of Scope [Explicit list of what this item does NOT cover. Forces scope discipline.] ## Target Backend Environment [ALWAYS required on a leaf — the SECTION is unconditional, only its VALUE is conditional. It is where `runtime_behavior_change` is persisted, so omitting it records nothing rather than recording "no". When the item changes runtime behavior, use an exact `deploy.branches` key. A human-confirmed value is a bare key or `Confirmed: `. An automated evidence write is `Inferred: — evidence: `; an automated generic default is `Assumption: — remote default branch `. Without a unique reverse-map use `Assumption: remote default branch `. Human confirmation replaces the automated annotation with a bare key or `Confirmed: `. ALWAYS render this section — it is where `runtime_behavior_change` is persisted, and an absent section reads as *underivable*, not exempt. Work that changes no runtime behavior declares the exemption in place of an environment: `None — no runtime behavior change: doc-only` (or `config-only` / `type-only`). A Project/container declares `None — container: state rolls up from children`. Visible prose, not an HTML comment, for the same reason the Branch Plan provenance line is: a marker that survives in only one representation cannot be a vendor-neutral discriminator, and every tracker this contract binds stores its body in some rich-text or structured form that need not preserve HTML comments. A declaration a reader can see is one every backend can store. See the `derived-branch-plan` rule.] ## Branch Plan [GENERATED, never hand-authored. Render only when the item has a Target Backend Environment; omit entirely when `runtime_behavior_change = false` (doc-only / config-only / type-only) or for a Project/container — absence is correct there. Derive per the `derived-branch-plan` rule: resolve the environment, map it forward through `.lisa.config.json` `deploy.branches`, and prove the branch exists on the remote. Do not accept caller-supplied branches; recompute them. Exactly three lines: Branch from: PR into: Derived from: Target Backend Environment via .lisa.config.json deploy.branches Both fields name the same branch by construction. A missing, ambiguous, or non-unique mapping, or a branch absent from the remote, STOPS the write — never default to `main` or the remote default to keep the write alive.] ## Sign-in Required [Include this section ONLY if the work touches authenticated surfaces. Specify: the account/role to sign in as, where to get the credentials (1Password item name, env var, seeded fixture), and any MFA/SSO notes. Omit the section entirely when sign-in is not required.] ## Repository [Required for Bug / Task / Sub-task. Name the single repo this item covers. If the work spans repos, this issue type is wrong — split into per-repo Tasks/Sub-tasks under a parent Story or Epic.] ## Validation Journey [Delegate to /linear-add-journey if the item changes runtime behavior. Skip only for doc-only, config-only, or type-only items. Cross-work-item evidence pointers use `[EVIDENCE-REF: | : ]`; they never replace this item's local S14 marker.] ``` Rules: - PRD-sourced Issues (caller passed `prd_source`) MUST carry the Source Requirement section with verbatim quotes — paraphrases are rejected (validator gate S16). This applies at every level, sub-issues included: a leaf claimed in isolation must explain its own "why". - Every acceptance criterion uses Given/When/Then. No vague "should work" language. - Every criterion is independently verifiable (UI, API, data, or performance check). - If the item is a Bug, include reproduction steps, expected vs. actual behavior, and environment. - If the item is a Spike, include the question being answered and the definition of done (decision doc, prototype, or findings). - If sign-in is required, the implementer must be able to sign in from the description alone — never assume they will guess the account or hunt for credentials. ## Phase 4 — Relationship Discovery (Mandatory) Before creating or updating, find candidate relationships. Do NOT skip — this is the step agents most often omit. ### 4a. Project Parent (Epic-equivalent) If the item is **not an Epic** and **not a top-level Bug/Spike**, it MUST have a parent context: - **Story / Task / Improvement** → must have a `projectId` (the Epic Project) set. - **Sub-task** → must have a `parentId` (the Story Issue) set. If the parent is explicitly provided, use it. Otherwise: 1. Search active Projects in the team: ```text lisa-linear-access operation: list-projects({team: , state: ["backlog", "planned", "started"]}) ``` Match on keywords from the summary and description. 2. If no matching Project exists, stop and ask the human to create or pick one. Do NOT orphan the item. ### 4b. Related Items Relationship discovery is **mandatory** on every create and every update — never declare "no related work" without doing both searches below and recording their outcomes on the item. **Search 1: local git history** (catches PRs / commits that touched the same area but were never linked): ```bash git log --all --oneline --grep="" git log --all --oneline -- git log --since=90.days --oneline -- ``` If the git search surfaces a PR or commit that relates to this work, capture the PR URL — it becomes a remote link (Phase 4c) and may also point to a sibling item worth linking. **Search 2: Linear MCP** (catches open and recently-closed items): ```text # Open items in the same Project lisa-linear-access operation: list-issues({project: , state_type: ["unstarted", "started"]}) # Open items with overlapping keywords (workspace-wide) lisa-linear-access operation: list-issues({query: "", state_type: ["unstarted", "started"]}) # Items with shared labels lisa-linear-access operation: list-issues({label: "