Work on a Linear issue by ID. Fetch issue details, classify it as a bug, task, or unclear request, gather the right context, create the Linear branch from latest master, implement simple changes, and verify with tests, lint, and typecheck. Bugs require root cause analysis and production evidence when useful. Tasks require clarified requirements, acceptance criteria, constraints, and tradeoffs.
Work on a Linear issue by ID. Fetch issue details, classify it as a bug, task, or unclear request, gather the right context, create the Linear branch from latest master, implement simple changes, and verify with tests, lint, and typecheck. Bugs require root cause analysis and production evidence when useful. Tasks require clarified requirements, acceptance criteria, constraints, and tradeoffs.
work-on
Use this skill when the user asks to work on a Linear issue or invokes
/skill:work-on <ISSUE-ID>.
Input
Required argument: Linear issue ID or identifier, for example LIN-123.
If the issue ID is missing or ambiguous, ask for it before doing anything else.
Non-negotiables
Classify the issue before implementation:
Bug or incident: root cause analysis is required before patching.
Task, feature, chore, refactor, docs, migration, or cleanup: clarify the
goal, scope, acceptance criteria, constraints, and tradeoffs before changing
code.
Unclear issue: ask for clarification or state the assumption before
continuing.
Do not fabricate production evidence. For bugs, use MCP or log sources when
they may clarify the issue. For tasks, only use production or admin data when
it is directly needed to understand scope, current behavior, or risk.
Protect user work. If the repo has uncommitted changes before branch setup,
stop and ask before stashing, committing, or overwriting anything.
Do not update Linear status, comments, assignees, or labels unless the user asks.
Prefer current project skills. Load any matching project or global skill with
read before using that workflow, for example TypeScript, backend, testing,
background processes, or git-spice.
Workflow
1. Intake and Linear context
Parse the issue ID from the skill argument.
Connect to Linear MCP if needed:
mcp({ connect: "linear" })
Fetch complete issue details:
linear_get_issue with id, includeRelations: true,
includeCustomerNeeds: true, and includeReleases: true.
Fetch comments:
linear_list_comments with issueId and limit: 250.
Fetch referenced attachments, documents, project resources, linked diffs, and
customer needs when they contain technical context.
Extract and keep these fields in the working notes:
If master does not exist, ask before using another trunk branch.
If the branch already exists, ask whether to check it out, reset it, or create a
new branch.
4. Load relevant local skills
Before deeper work, inspect the project context and load matching skills. Examples:
TypeScript or JavaScript project: load any available TypeScript or JS skill.
Long-running dev server, watcher, or log tail: load the background process skill.
Stacked or multi-stage work: load the git-spice skill before proposing a stack.
Domain-specific project skills: load those before editing that subsystem.
If no matching skill exists, continue and state that no matching skill was found.
5. Context gathering
Gather only the context needed for the issue classification.
For bugs and incidents, build a timeline before changing code. Use the issue
details to define:
time window
affected routes, services, jobs, workers, queues, cron tasks, or APIs
request IDs, trace IDs, user IDs, organization IDs, team IDs, customer IDs
deploys, releases, flags, experiments, or config changes around the incident
For tasks, gather enough context to understand:
desired outcome
acceptance criteria
affected users or systems
existing behavior
product or technical constraints
rollout, migration, or compatibility concerns
current patterns that the implementation should follow
Use the MCP sources below only when they are relevant to the issue
classification.
Datadog MCP
Use Datadog MCP for logs, traces, metrics, RUM, dashboards, and error events when
production evidence may clarify a bug, incident, task scope, or rollout risk.
Connect or inspect tools:
mcp({ connect: "datadog" })
mcp({ server: "datadog" })
mcp({ search: "logs", server: "datadog" })
Query narrowly first by request ID, trace ID, org ID, user ID, route, service,
status code, exception name, and the issue time window.
Broaden only if the narrow query returns nothing.
Capture exact evidence: timestamps, service names, error messages, stack
frames, deploy version, trace links, and metric changes.
Cloudflare MCP
Use Cloudflare MCP for edge analytics, worker errors, WAF or rate-limit events,
cache behavior, request paths, zones, and network-level failures when they matter
for the bug or task.
Search for the right Cloudflare API endpoints first:
cloudflare_search
Execute focused API requests:
cloudflare_execute
Correlate Cloudflare timestamps, status codes, colo, path, host, worker route,
firewall action, cache status, and Ray IDs with Linear and Datadog evidence.
linear-admin MCP
Use linear-admin only when the issue needs deeper data investigation that normal
Linear issue details cannot answer.
Find the organization when needed:
linear_admin_find_organizations
Use the organization's region for admin database questions:
linear_admin_ask_database
Use natural language questions. Do not write raw SQL unless explicitly asked.
Good questions are specific and bounded, for example:
"For organization , what recent errors or state transitions relate to issue ?"
"For user , what records changed around that could explain ?"
"For organization , how many records would be affected by the requested migration?"
Treat database output as evidence. Cross-check it with code before deciding the
root cause, implementation approach, or task scope.
6. Local codebase investigation
Inspect the codebase until the bug cause or task implementation path is supported
by evidence.
Identify project type and commands:
read package.json, lockfiles, build files, test configs, service configs
use detect_package_manager before package-manager commands
API clients, schema validators, serialization and permission checks
existing components, service patterns, or docs related to the requested task
Trace the relevant execution path end to end:
input boundary
validation and auth
business logic
persistence or external API calls
response, event, or job side effects
For bugs, reproduce locally when practical.
For tasks, inspect existing patterns and call sites before choosing an
implementation.
Add or run targeted tests that demonstrate the bug before fixing, or validate
the task acceptance criteria, when the project structure makes that reasonable.
7. Analysis gate
Before editing, write a short note for yourself and use it to decide whether to
implement now.
For bugs, the note must include:
symptom
affected scope
confirmed evidence from Linear, logs, data, Cloudflare, local repro, or code
hypotheses considered
hypotheses eliminated and why
most likely root cause
why this file or subsystem is the correct fix location
For tasks, the note must include:
requested outcome
acceptance criteria
affected files or subsystems
constraints and tradeoffs
implementation approach
verification plan
If the bug root cause is not clear, do not patch randomly. Ask the user for
missing context or propose the next investigation step.
If the task requirements are not clear, ask for clarification before building the
wrong thing confidently.
8. Implementation decision
Implement immediately only when:
the issue is understood
the change is localized enough to review safely
risk is low or manageable
tests or manual checks can verify it
no unresolved product or architecture decision remains
If the change has multiple parts or meaningful tradeoffs, stop and propose
options. For each option include:
implementation summary
files or subsystems touched
risk
verification plan
rollback or rollout notes
recommendation
If the work requires a multi-stage rollout, compatibility window, data migration,
API migration, or reviewable stack of changes, suggest using git-spice and load
the git-spice skill before designing the branch stack.
9. Implementation rules
Make the smallest change that addresses the proven bug cause or agreed task
scope.
Keep existing style and architecture.
Do not add dependencies unless necessary. Ask first if a new dependency is not
clearly justified.
Do not mix unrelated refactors with the change.
For tasks, do not expand scope beyond the issue and clarified acceptance
criteria without asking.
Update tests, fixtures, docs, migrations, or config when the change affects
behavior or contracts.
10. Verification
After implementing a change, verify it before reporting completion.
Run targeted tests for the changed area.
Run available project checks, usually:
tests
lint
typecheck
build when relevant
Use detect_package_manager and project scripts to choose commands.
If a check is missing, say it is missing. If a check fails for an unrelated
pre-existing reason, show the evidence.
For bugs, re-run or reproduce the original failing path when practical.
For tasks, validate the acceptance criteria when practical.
Review the final diff with git diff.
11. Final response
Report concisely:
branch created or used
issue classification
issue summary
for bugs: root cause
for tasks: requirements and implementation approach
change made, or options if no change was applied
verification commands and results
remaining risks or follow-up work
Do not claim the bug is fixed or the task is complete unless verification passed
or you clearly explain what could not be verified.
