Write Issues

Write issues a teammate can act on without asking you follow-up questions. Lead with what the reader needs to reproduce or understand the request, not with your analysis.

Show a draft first and let the user react before you create anything in Linear.

1. Title

Prefix the title with the type in parentheses, the same way the repo prefixes PRs.

• (bug) for something broken.
• (feat) for a new capability or improvement.
• Other types as needed: (chore), (docs).

State the symptom or the request in plain words. Keep it short.

• Good: (bug) Feedback sent via the API can't be filtered in observability
• Good: (feat) Filter evaluation results by metric value
• Bad: (bug) Annotation filter options array empty due to thin refs (that is the root cause, not the symptom)
• Bad: Observability issue (vague)

2. Body — bugs

Do not open with a "Context" heading. Start with the reproduction, in the user's voice: when I do this, I expect that, but instead this happens. Or: this code is supposed to do X, but it does Y. Keep the words simple.

Then give the concrete information a teammate needs to debug it, when you have it:

• Exact steps to reproduce, numbered.
• Requests and responses (the call you made and what came back).
• Errors, console output, or relevant log lines.
• Screenshots or screen recordings.
• Where it reproduces (local, preview, Railway, cloud) and the version if known.

That is the whole job: make it reproducible. Include real payloads over descriptions of them.

3. Do not write the root cause

The issue tracks the problem, not the investigation. Do not add a "root cause" or "why this happens" section. That analysis belongs in the PR that fixes it (see the write-pr-description skill). Keep the issue about observable behavior and the information needed to debug it.

If you already know the cause, it still does not go in the issue body. Put it in the PR.

4. Body — feature requests

Lead with the problem or the goal from the user's point of view: what they are trying to do and why it is hard today. Then describe the behavior they want. Skip implementation design unless the user asked for it.

5. Todo list

Add a checkbox list only when delivery is split across stacked PRs or has several ordered steps. One line per step, written as an outcome.

- [ ] Fix the filter so it reads the evaluator's real feedback metrics.
- [ ] Fix how the frontend reads the feedback type so the nested schema is understood.

If a single PR closes the whole issue, skip the todo list. Do not pad an issue with checkboxes for its own sake.

6. Linear fields

File issues on the Agenta team (key AGE). Pick the fields deliberately.

Project (set one):

• Bugs — the default home for bug reports.
• Quality of life improvements — small improvements that do not belong to a feature project.
• The active feature project when the work is part of one (for example Annotation Queues, Core Loop Improvements, Reliability Availability Scalability & Performance, Documentation, New integrations for observability, DevSecOps & DevEx). List active projects with mcp__linear-server__list_projects and match by area.

Labels (combine a type label with the relevant area labels):

• Type: Bug Report, Feature Request, Question, Chore, refactoring, tech-debt. Use unconfirmed bug or reproduction-needed when you could not reproduce it yet.
• Area: frontend, Backend, SDK, API, observability, Tracing, Workflows, evaluation, human evaluation, playground, prompt management, Services, database, infrastructure, integration, security, analytics.
• UX: UX, ux bug, dev experience.
• Visibility: Public marks an issue mirrored to the public GitHub repo. This is the label the GitHub sync watches, so set it when you want the linked GitHub issue created (see section 7). Use Core Team / Internal Team for internal-only issues.

Priority (0 None, 1 Urgent, 2 High, 3 Medium, 4 Low):

• 1 Urgent: data loss, outage, or drop-everything.
• 2 High: important and should land soon.
• 3 Medium: the default for a normal bug.
• 4 Low / 0 None: minor or nice-to-have.

State flow: Todo → In Progress → In Review → In QA → Done. Use Backlog for later, Canceled / Duplicate as needed. New issues start in Todo; move to In Progress once work has started.

7. Filing it and linking the PR

Create with mcp__linear-server__save_issue (no id field creates a new issue). Pass team, title, description (Markdown, literal newlines), project, labels, priority. Link related issues with relatedTo, and attach the PR with links ([{url, title}]).

The workspace runs a Linear ↔ GitHub sync that creates a linked GitHub issue when the Public label is set. After creating the Linear issue, find the auto-created GitHub issue (gh issue list --repo Agenta-AI/agenta --search "<keywords>", allow a few seconds for the sync), then link the PR to it by adding Closes #<n> (or Refs #<n> when the PR is only part of the issue) to the PR body. The sync then moves the Linear issue as the PR opens and merges.

To move the issue yourself, call save_issue again with the issue id and state: "In Progress".

8. Checklist before you create

• Title prefixed with (bug) / (feat) and states the symptom or request, not the cause.
• Bug opens with reproduction in plain words, then steps + real requests/responses/logs.
• No root-cause section.
• Todo list only if the work is stacked or multi-step.
• Team, project, labels, priority set. Public added if it should sync to GitHub.
• After creating: GitHub issue found, PR links to it, Linear state set as the user asked.