Linear Bug Report Template for State Dependent Browser Bugs

A useful Linear bug report lets the fixing teammate reproduce the browser problem without first interviewing the reporter. It names the starting state, records the exact action order, separates expected from actual behavior, and identifies the first result that disagreed.

The template below is designed for browser bugs that depend on a workspace, account, tab, feature flag, cart, permission, or other state a fresh page can erase. Copy it into a Linear standard template or form template, remove fields that do not apply, and keep the smallest safe path that still reproduces the issue.

Copyable Linear bug report template

Issue title
[Actor + action + wrong result]

# Summary
[What went wrong, where, and after which action?]

## Impact
[Who is blocked or at risk? What work cannot continue?]

## Environment
- App or URL:
- Build or release:
- Browser and version:
- Operating system:
- Viewport or device:
- Account role:
- Workspace, project, or record:

## Starting state
[What must already be true before step 1? Include the active account, open tabs, selected record, saved browser state, and relevant flags.]

## Steps to reproduce
1. [Action]
2. [Action]
3. [Action]

## Expected result
[What should the browser and server-backed state show?]

## Actual result
[What did the browser show, and what did the request or persisted record show?]

## First mismatch
[Name the earliest point where expected and actual behavior diverged.]

## Focused technical context
- Console:
- Network request and response:
- DOM or locator:
- Storage or cookie state:
- Timestamp and timezone:

## Control check
[Describe a clean path that passes, such as a fresh tab, direct navigation, or a single-workspace run.]

## Safe reproduction notes
[Test data, permissions, cleanup, privacy masking, and actions that must not touch production.]

## Acceptance check
[The exact browser-visible and persisted result that proves the fix.]

The point is not to complete every line. The point is to preserve the fields that determine whether another person can recreate the same state and confirm the same result.

How to configure the template in Linear

Linear supports standard issue templates and form templates. Its documentation says standard templates can preset issue properties and description context. Form templates add structured fields, including required fields, and can be used through supported intake routes such as Slack and Linear Asks.

Use a standard template when the reporting team already knows which details matter and needs a flexible description. Use a form template when missing preconditions, environment, or expected behavior repeatedly sends the issue back to the reporter.

A practical Linear setup is:

Do not make the form longer just because Linear allows more fields. Required fields should answer a receiver question. If a field never changes triage, diagnosis, or acceptance, remove it.

A controlled two-tab browser example

We built a synthetic localhost fixture with two browser tabs and local storage only. It used invented workspaces and a fictional member. It made no account, network, or production changes.

Tab A opened Alex's member page in the Northwind workspace. Tab B then changed the globally active workspace to Acme. When Tab A clicked Remove Alex, the page displayed a success message claiming Alex had been removed from Northwind. The underlying audit record showed that the action actually targeted Acme.

The captured failure path was:

A screenshot of the success message would support the wrong conclusion. The decisive fact was the disagreement between the stale page context and the workspace used by the request.

The worked Linear issue

Here is how that failure fits the template.

Summary

Removing a member from a stale Northwind tab sends the action to Acme after another tab changes the active workspace.

Impact

An administrator can believe access was removed from one workspace while the request applies to another. Use only synthetic accounts until the routing is fixed.

Environment

• Synthetic localhost fixture

• Desktop Chromium

• Two tabs sharing browser storage

• Administrator role

• Workspaces Northwind and Acme

• Fictional member Alex

Starting state

Open Alex's Northwind member page in Tab A. Keep it open. Open Tab B with Northwind active. Both tabs share the same local browser storage.

Steps to reproduce

1. In Tab B, switch the active workspace from Northwind to Acme.

2. Return to the already-open Northwind member page in Tab A.

3. Click Remove Alex.

4. Read the success message.

5. Inspect the request target or synthetic audit record.

Expected result

The action should remain bound to the Northwind member page, or the interface should block and ask the administrator to reload after the workspace changes.

Actual result

The page says Alex was removed from Northwind, while the action uses Acme as its target workspace.

First mismatch

The first mismatch appears before the action is sent. Tab A still renders Northwind while its shared active-workspace state has changed to Acme.

Focused technical context

The page identity was captured when Tab A loaded. The action handler read the current global workspace at click time. The visible confirmation used the page identity instead of the request target. Those three values must be compared in the same report.

Control check

Reset the active workspace to Northwind, reload the member page, and perform the removal without changing workspaces in another tab. In the clean control, the opened workspace and request target both remain Northwind.

Acceptance check

Repeat the two-tab sequence. The action must either remain bound to Northwind or stop with a clear stale-context warning. The browser message, request target, and persisted result must name the same workspace.

Why each section earns its place

A good bug report is not a diary of everything the reporter noticed. Each section answers a decision the receiver must make.

The practitioner discussion that informed this guide asked for dev-friendly bug reports that reduce back-and-forth and make issues reproducible and testable without stakeholder filler. That is a useful editing rule. Keep what changes the receiver's next action. Cut everything else.

Common Linear bug report mistakes

Starting at the final screen

The final screen often reflects the wrong state without explaining how it arrived there. Record the account, workspace, record, and tab state before the decisive action.

Using a screenshot as the reproduction path

A screenshot is useful for layout, copy, and visible-state defects. It cannot show which workspace a request targeted, what another tab changed, or which state existed before the click.

Listing many logs without naming the first mismatch

A long console dump makes the receiver search the report again. Quote the smallest relevant signal and explain why it conflicts with the expected result.

Leaving the control path out

A passing nearby path narrows the diagnosis. In this example, the clean one-tab control showed that the failure required the cross-tab workspace transition.

Writing acceptance as a vague outcome

"Works correctly" is not testable. Name the browser-visible result and the persisted result that must agree.

When to attach more than text

Text is enough when the issue depends on a short deterministic path and the relevant technical signal is small. Add a screenshot when visual layout matters. Add a Playwright trace when an automated test owns the path. Add a deliberately captured browser path when a fresh page removes the starting state or action order.

For a broader tool decision, use the guide to tools for reproducing front-end bugs. If your team files in Jira instead, copy the worked Jira bug report template. Support teams can also use the browser bug escalation checklist before routing the issue.

If the hard part is preserving the browser transition before it reaches Linear, install CSS Selector & XPath Finder by Samelogic. A QA practitioner, support operator, product teammate, developer, or permitted end user deliberately starts capture before repeating the bounded flow, then sends the exact page context and action path to the teammate fixing it.

Sources

• Linear issue templates documentation

• Practitioner discussion about dev-friendly bug report templates