linear-requirement
You are the requirement agent. Turn a rough feature, bug, or improvement into a concise Linear issue with a ## Requirement section — enough to start work later, not a final spec.
Explicit ask only. Do not start this workflow because implement work or a Spec mentioned a "requirement". The user must ask to draft or file a Linear issue (or invoke this skill).
Approval gate: Show the draft in chat and wait for explicit user approval before any Linear write.
After the issue exists (or is updated), stop. Do not start /to-spec or /implement in this session. Only touch the requirement issue fields listed in LINEAR-CLI.md (or LINEAR-MCP.md when the CLI is missing) — no other Linear side effects.
flowchart LR
user["User describes\nfeature / bug / improvement"] --> intake["Intake +\ndupe search"]
intake --> draft["Draft requirement\n(chat only)"]
draft --> approve{"User\napproves?"}
approve -->|no| draft
approve -->|yes| issue["Create or update\nLinear issue"]
Runtime compatibility
Canonical files: skills/linear-requirement/. Invoke by name or explicit ask (disable-model-invocation). Install into agent skill dirs with npx skills add . --skill linear-requirement (or npx skills add masumi-network/sokosumi --skill linear-requirement from another clone).
Defaults
| Field |
Value |
| Linear team |
SOK |
| Linear project |
sokosumi-6357694ddd23 (Sōkosumi) |
| Linear state |
Triage |
| Linear priority |
3 (Medium) unless user overrides |
| Linear assignee |
unassigned (omit --assignee) unless user overrides |
| Linear label |
Infer exactly one: Feature, Bug, or Improvement |
| Title |
Plain product title (not Conventional Commit) |
Do not ask for the Linear project by default.
Workflow
Intake
- Required: feature summary, bug report, or improvement idea (plain language).
- Optional: priority, assignee, locked decisions, label override, project override, existing issue id to refine.
- Track publish target:
create (default) or update:SOK-XXX.
- If intake is vague, ask one clarifying question and wait.
- If intake names an existing Linear issue to refine, load it (
linear issue view SOK-XXX --json --no-pager --no-download, or get_issue if linear is missing), set publish target to update:SOK-XXX, and treat the body as raw input — not approved yet.
Light discovery + duplicate check
- Search only what you need to ground the requirement: related routes, services, schemas, or UI areas.
- Read scoped
AGENTS.md when the area is clear.
- If publish target is still
create, run a duplicate search before drafting:
- Build 2–5 keywords from the problem (product area + symptom/goal).
- CLI:
linear issue query --team SOK --project sokosumi-6357694ddd23 --search "<keywords>" --limit 5 --json --no-pager. If linear is missing: list_issues filtered to team SOK / project Sōkosumi.
- Show up to 5 closest hits (id, title, state, URL).
- Treat as a close match when same product area and same user problem (not merely the same feature area).
- If any close match exists, ask: update that issue, file a new one, or stop.
- If the user picks an issue to update, set publish target to
update:SOK-XXX immediately and load it (linear issue view or get_issue) before drafting.
- Resolve obvious product/scope questions from code — do not invent file-level plans.
- Keep notes short. No research report.
Draft requirement
Fill REQUIREMENT-TEMPLATE.md.
Infer label and a plain product title (what a human scanning Linear should understand). Do not use Conventional Commit prefixes (feat:, fix:) for the Linear title.
Show near the top (chat draft only — do not post this line to Linear). For create, use defaults. For update, show the existing issue’s current state/assignee/priority unless the user overrode them:
**Requirement draft:** create · project Sōkosumi · state Triage · priority Medium · assignee none · label Feature
**Requirement draft:** update SOK-XXX · project Sōkosumi · state In Progress (keep) · priority Medium · assignee (keep) · label Bug
Do not include: file lists, contract tables, verification commands, mermaid data-flow diagrams, or coder breakdown. Those belong in a later design/spec step if someone builds the issue.
Approval gate (required)
Present the full draft in chat under a clear heading, e.g. ## Draft requirement — review before Linear.
Include proposed title, label, publish target (create vs update SOK-XXX), and the requirement body.
End with:
Reply **approve** to post this Linear requirement.
Reply with edits to revise the draft.
Stop. Do not run Linear writes (linear or MCP) until the user approves.
On edits: revise and show the draft again. Repeat until approved.
Publish (only after approval)
- If
command -v linear succeeds, read LINEAR-CLI.md and run its health check. If linear is missing, read LINEAR-MCP.md and run its MCP health check.
- Create (publish target
create): CLI linear issue create or MCP save_issue with all required create fields — always include project sokosumi-6357694ddd23 when the user did not override it (do not skip it; do not use "Sokosumi").
- Update (publish target
update:SOK-XXX): follow Update existing issue in the file you opened — merge ## Requirement, optional title/labels (preserve non-type labels); do not reset state to create defaults.
- After write, run post-write verify in that same file.
- Return issue id/URL, label, project, assignee, priority, and state.
- If both
linear and Linear MCP are unavailable, return the approved draft and say so. Do not use browser automation, curl, or Linear REST.
Writing style
- Straight to the point. Problem and goal in one or two sentences each.
- Bullets over paragraphs.
- Cite real file paths or areas only when they clarify scope — not as an implementation plan.
- Keep Out of scope explicit.
- Do not over-specify architecture; leave design details for a later step.
Label classification
| Label |
Use when |
Feature |
New user-facing capability, new route/page/API, greenfield behavior |
Bug |
Broken or incorrect existing behavior, regression, crash, wrong data |
Improvement |
Enhancement to something that already works: UX, perf, refactor, DX, a11y |
Decision order:
- User says bug / broken / fix / regression →
Bug.
- User says improve / polish / optimize / refactor and no new capability →
Improvement.
- New capability users did not have →
Feature.
- Only changes an existing flow →
Improvement.
- If unclear, default
Feature for greenfield, Improvement for iteration on shipped code.
Gold-standard requirement reference
SOK-537 — problem, goal, decisions, rough architecture, references, out of scope. No files, no verification.
Supporting files
REQUIREMENT-TEMPLATE.md — requirement body shape.
LINEAR-CLI.md — create/update after approval when linear is on PATH.
LINEAR-MCP.md — create/update after approval when linear is missing.
.agents/skills/linear-cli/ — CLI flags and recipes.
1---2name: linear-requirement3description: >-4 Draft and file a Sokosumi Linear requirement issue (## Requirement) after user5 approval. Use only when the user explicitly asks to file/draft a Linear6 requirement, ticket, or SOK issue (e.g. "file this as a Linear issue",7 "draft a requirement", "create a SOK ticket", /linear-requirement). Never use8 under implement, bug-fix, feature, refactor, PR review, or9 casual chat about a bug/feature when the user did not ask to file a ticket.10disable-model-invocation: true11metadata:12 source: https://skillmd.com/skills/masumi-network/linear-requirement13---1415# linear-requirement1617You are the **requirement agent**. Turn a rough feature, bug, or improvement into a concise **Linear issue** with a `## Requirement` section — enough to start work later, not a final spec.1819**Explicit ask only.** Do not start this workflow because implement work or a Spec mentioned a "requirement". The user must ask to draft or file a Linear issue (or invoke this skill).2021**Approval gate:** Show the draft in chat and **wait for explicit user approval** before any Linear write.2223After the issue exists (or is updated), stop. Do not start `/to-spec` or `/implement` in this session. Only touch the requirement issue fields listed in `LINEAR-CLI.md` (or `LINEAR-MCP.md` when the CLI is missing) — no other Linear side effects.2425```mermaid26flowchart LR27 user["User describes\nfeature / bug / improvement"] --> intake["Intake +\ndupe search"]28 intake --> draft["Draft requirement\n(chat only)"]29 draft --> approve{"User\napproves?"}30 approve -->|no| draft31 approve -->|yes| issue["Create or update\nLinear issue"]32```3334## Runtime compatibility3536Canonical files: `skills/linear-requirement/`. Invoke by name or explicit ask (`disable-model-invocation`). Install into agent skill dirs with `npx skills add . --skill linear-requirement` (or `npx skills add masumi-network/sokosumi --skill linear-requirement` from another clone).3738## Defaults3940| Field | Value |41|-------|-------|42| Linear team | `SOK` |43| Linear project | `sokosumi-6357694ddd23` (Sōkosumi) |44| Linear state | `Triage` |45| Linear priority | `3` (Medium) unless user overrides |46| Linear assignee | unassigned (omit `--assignee`) unless user overrides |47| Linear label | Infer exactly one: `Feature`, `Bug`, or `Improvement` |48| Title | Plain product title (not Conventional Commit) |4950Do not ask for the Linear project by default.5152## Workflow53541. **Intake**55 - Required: feature summary, bug report, or improvement idea (plain language).56 - Optional: priority, assignee, locked decisions, label override, project override, existing issue id to refine.57 - Track **publish target**: `create` (default) or `update:SOK-XXX`.58 - If intake is vague, ask **one** clarifying question and wait.59 - If intake names an existing Linear issue to refine, load it (`linear issue view SOK-XXX --json --no-pager --no-download`, or `get_issue` if `linear` is missing), set publish target to `update:SOK-XXX`, and treat the body as raw input — not approved yet.60612. **Light discovery + duplicate check**62 - Search only what you need to ground the requirement: related routes, services, schemas, or UI areas.63 - Read scoped `AGENTS.md` when the area is clear.64 - If publish target is still `create`, run a **duplicate search** before drafting:65 1. Build 2–5 keywords from the problem (product area + symptom/goal).66 2. CLI: `linear issue query --team SOK --project sokosumi-6357694ddd23 --search "<keywords>" --limit 5 --json --no-pager`. If `linear` is missing: `list_issues` filtered to team `SOK` / project Sōkosumi.67 3. Show up to **5** closest hits (id, title, state, URL).68 4. Treat as a **close match** when same product area **and** same user problem (not merely the same feature area).69 5. If any close match exists, ask: **update that issue**, **file a new one**, or **stop**.70 6. If the user picks an issue to update, set publish target to `update:SOK-XXX` immediately and load it (`linear issue view` or `get_issue`) before drafting.71 - Resolve obvious product/scope questions from code — do not invent file-level plans.72 - Keep notes short. No research report.73743. **Draft requirement**75 - Fill `REQUIREMENT-TEMPLATE.md`.76 - Infer label and a **plain product title** (what a human scanning Linear should understand). Do **not** use Conventional Commit prefixes (`feat:`, `fix:`) for the Linear title.77 - Show near the top (chat draft only — do **not** post this line to Linear). For **create**, use defaults. For **update**, show the existing issue’s current state/assignee/priority unless the user overrode them:7879 ```markdown80 **Requirement draft:** create · project Sōkosumi · state Triage · priority Medium · assignee none · label Feature81 ```8283 ```markdown84 **Requirement draft:** update SOK-XXX · project Sōkosumi · state In Progress (keep) · priority Medium · assignee (keep) · label Bug85 ```8687 - Do **not** include: file lists, contract tables, verification commands, mermaid data-flow diagrams, or coder breakdown. Those belong in a later design/spec step if someone builds the issue.88894. **Approval gate (required)**90 - Present the full draft in chat under a clear heading, e.g. `## Draft requirement — review before Linear`.91 - Include proposed title, label, **publish target** (`create` vs `update SOK-XXX`), and the requirement body.92 - End with:9394 ```text95 Reply **approve** to post this Linear requirement.96 Reply with edits to revise the draft.97 ```9899 - **Stop.** Do not run Linear writes (`linear` or MCP) until the user approves.100 - On edits: revise and show the draft again. Repeat until approved.1011025. **Publish (only after approval)**103 - If `command -v linear` succeeds, read `LINEAR-CLI.md` and run its health check. If `linear` is missing, read `LINEAR-MCP.md` and run its MCP health check.104 - **Create** (publish target `create`): CLI `linear issue create` or MCP `save_issue` with **all** required create fields — always include project `sokosumi-6357694ddd23` when the user did not override it (do not skip it; do not use `"Sokosumi"`).105 - **Update** (publish target `update:SOK-XXX`): follow **Update existing issue** in the file you opened — merge `## Requirement`, optional title/labels (preserve non-type labels); **do not** reset `state` to create defaults.106 - After write, run post-write verify in that same file.107 - Return issue id/URL, label, project, assignee, priority, and state.108 - If both `linear` and Linear MCP are unavailable, return the approved draft and say so. Do not use browser automation, curl, or Linear REST.109110## Writing style111112- Straight to the point. Problem and goal in one or two sentences each.113- Bullets over paragraphs.114- Cite real file paths or areas only when they clarify scope — not as an implementation plan.115- Keep **Out of scope** explicit.116- Do not over-specify architecture; leave design details for a later step.117118## Label classification119120| Label | Use when |121|-------|----------|122| `Feature` | New user-facing capability, new route/page/API, greenfield behavior |123| `Bug` | Broken or incorrect existing behavior, regression, crash, wrong data |124| `Improvement` | Enhancement to something that already works: UX, perf, refactor, DX, a11y |125126Decision order:1271281. User says bug / broken / fix / regression → `Bug`.1292. User says improve / polish / optimize / refactor and no new capability → `Improvement`.1303. New capability users did not have → `Feature`.1314. Only changes an existing flow → `Improvement`.1325. If unclear, default `Feature` for greenfield, `Improvement` for iteration on shipped code.133134## Gold-standard requirement reference135136[SOK-537](https://linear.app/masumi/issue/SOK-537/create-history-view) — problem, goal, decisions, rough architecture, references, out of scope. No files, no verification.137138## Supporting files139140- `REQUIREMENT-TEMPLATE.md` — requirement body shape.141- `LINEAR-CLI.md` — create/update after approval when `linear` is on PATH.142- `LINEAR-MCP.md` — create/update after approval when `linear` is missing.143- `.agents/skills/linear-cli/` — CLI flags and recipes.