Write Linear Issues Ready for AI Agent Automation

AI agent automation starts before the agent runs. It starts in the issue.

That is especially true for Linear issue-to-pull-request workflows. Switchboard can watch Linear, route work to a daemon, spawn an isolated worktree, run Claude Code or Codex, and produce a pull request path. But it should not be treated as a way to rescue vague tickets. If the Linear issue is ambiguous, the run will inherit that ambiguity.

The useful question is not "Can an agent work on this?" It is "Is this issue ready to become a bounded, reviewable branch?"

This guide is about that pre-automation step: how to write Linear issues that are specific enough for Switchboard, narrow enough for an isolated worktree, and clear enough for a human reviewer to evaluate when the pull request comes back.

Why issue quality matters more with automation

A human engineer can ask clarifying questions, remember team history, and notice when a ticket is missing context. An AI coding agent can ask questions too, but automation gets weaker when every run starts by discovering that the issue was not ready.

For Switchboard, the issue is the handoff. It should contain enough information for the agent to start the right work and for the reviewer to know whether the output matches the request.

Linear's own API model treats issues as structured objects with titles, descriptions, teams, states, comments, labels, and updates. The Linear GraphQL API docs show how issues can be queried and updated as data, and the Linear API and webhooks docs explain that issue and comment changes can trigger webhook-driven integrations.

That structure is useful, but structure alone is not enough. A short title and a vague description can still produce a bad automation run. The content of the issue has to do real work.

The readiness definition

A Switchboard-ready issue is:

• bounded,
• concrete,
• attached to the right repository,
• small enough for one isolated worktree,
• clear about acceptance criteria,
• and reviewable as a pull request.

If an issue fails those tests, keep it manual for now. That is not a failure of automation. It is a sign that the issue still needs product or engineering judgment before implementation starts.

What a ready issue includes

Start with one clear task. A good automation issue should not ask for a redesign, a bug fix, a migration, and a docs pass in the same ticket. If the work has several independent outcomes, split it.

Add the relevant context. Mention the product surface, repository, component, endpoint, command, failing test, or user-visible behavior. The agent should not have to infer the entire starting point from a sentence.

Write acceptance criteria that can be checked. Good criteria look like:

• the empty state message updates on the pricing page,
• the existing unit test passes,
• the new validation case rejects missing setup commands,
• the pull request only touches the setup copy and related tests.

Name the non-goals. If the issue should not touch billing logic, provider authentication, or database schema, say that. A short "do not change" section can save a lot of cleanup.

Give the reviewer a clear finish line. The best issue makes it obvious whether the resulting pull request did the job.

What is not ready

Some issues are poor automation candidates until they are broken down.

Avoid sending issues like:

• "Improve onboarding."
• "Make the app feel faster."
• "Clean up pricing."
• "Refactor the dashboard."
• "Fix the auth edge cases."
• "Make Switchboard smarter."

Those might be real problems, but they are not implementation-ready. They need triage, scope, design choices, or a human plan first.

Also be careful with work that touches shared state, destructive actions, migrations, production configuration, or cross-service behavior. An agent can help investigate those areas, but fully automated implementation should wait until the issue is specific and the risk is understood.

A practical issue template

Use a compact template like this:

## Goal
What should be true when this is done?
 
## Context
Where is the issue? Include route, component, package, command, or failing test.
 
## Acceptance Criteria
- Observable result 1
- Observable result 2
- Test or verification expectation
 
## Constraints
- Files or areas to avoid
- No schema changes unless explicitly requested
- Keep the change scoped to this behavior
 
## Review Notes
What should the reviewer pay attention to in the PR?

This does not need to be bureaucratic. It just needs to prevent the agent from guessing the parts a human already knows.

A good issue example

Here is a better automation candidate:

## Goal
Update the setup page copy so the daemon install step uses the current command.
 
## Context
The setup page lives in packages/site/src/pages/setup.tsx.
The current install command should be:
npm install -g @junctionpanel/junction-daemon
 
## Acceptance Criteria
- The setup page shows the current install command.
- Existing setup page tests still pass.
- Do not change pricing, provider setup, or homepage copy.
 
## Review Notes
Confirm this is a copy-only change unless a test fixture needs updating.

That issue is narrow. It names the file, expected output, verification path, and non-goals. A Switchboard run can attempt it in an isolated worktree, and a reviewer can quickly tell whether the pull request stayed in scope.

A bad issue example

Now compare this:

Improve setup because users are confused.

That may be a valid product concern, but it is not ready for automation. Confused about what? Install command? Provider login? Pairing? Pricing? Mobile access? The issue asks the agent to make product decisions without the context to make them well.

A better path is to split it:

• fix the outdated install command,
• add one sentence explaining daemon pairing,
• clarify provider authentication ownership,
• add a test for copyable command behavior.

Each smaller issue can become a reviewable pull request.

Where Switchboard fits

Switchboard is Junction's automation layer for Linear-driven work. It is built for the moment after the issue is ready.

The workflow is:

1. A Linear issue is scoped clearly enough to automate.
2. Switchboard picks up the configured work.
3. Junction runs the agent on the selected daemon.
4. The run uses an isolated worktree and branch path.
5. The result becomes a pull request for human review.

If you want the full mechanics, read How Switchboard Turns Linear Issues Into Pull Requests. If you want the Git isolation model behind the workflow, read Git Worktree Isolation for AI Coding Agents.

The tradeoff: automation rewards discipline

The more automatic the workflow, the more important the input becomes.

Manual agent sessions can absorb messy prompts because the human is present to steer the conversation. Switchboard is better for work that is already scoped. That does not make it less powerful. It makes it predictable.

Good automation habits look like:

• split large issues into smaller ones,
• keep acceptance criteria concrete,
• avoid bundling unrelated changes,
• include tests or verification expectations,
• and write non-goals when a task could easily drift.

Those habits help human engineers too. Switchboard just makes the payoff more visible.

A readiness checklist

Before tagging or routing an issue for automation, ask:

• Can one pull request satisfy this?
• Can one isolated worktree contain the change?
• Does the issue name the right repository or product area?
• Are the acceptance criteria observable?
• Is the expected test or verification path clear?
• Are risky areas called out?
• Would a reviewer know when to approve the PR?

If the answer is no, rewrite the issue before sending it to automation.

Next step

When your issues are ready for automation, compare the Junction plans and look at the Switchboard workflow. If you still need to connect the daemon first, start with the setup guide.