Copy the template below into a Linear issue description or your team's saved issue template. Replace bracketed prompts and remove irrelevant sections. Examples are synthetic teaching fixtures, not observed product incidents. The corrected example illustrates a more complete draft; unresolved owner decisions still need answers.
Copyable template
# [Specific change and affected flow]
## Problem
[Who is affected, what happens now, and why change it?]
## Expected behavior
[Observable result; record decisions and unresolved questions explicitly.]
## Acceptance criteria
- [ ] [Given a state, when an action happens, then an observable result follows.]
- [ ] [Boundary or failure behavior.]
## Scope and context
[Relevant service/component; in scope; out of scope; dependencies and owner.]
## Verification
[How to check success; safe fixtures; expected results.]
## States and accessibility
[Loading/empty/error/success; permissions; copy; keyboard/focus; responsive behavior.]Weak example
Improve empty state
Make projects look better when empty.
Corrected example
# Show a useful empty state on the project list
## Problem and expected behavior
Synthetic example: when a workspace has zero projects, the loaded project list is blank. Show “No projects yet” with “Create a project” for members who already have project-create permission. Users without permission see “Ask a workspace admin to create a project.”
## Acceptance criteria
- [ ] The empty state appears only after a successful load returns zero projects; loading and network errors retain their existing states.
- [ ] The create button opens the existing creation flow and returns focus to the trigger if canceled.
- [ ] A keyboard user can reach and activate the button, with a visible focus indicator.
- [ ] The heading and action have accessible names; a screen reader can distinguish the empty state from loading and errors.
- [ ] At 320 CSS pixels and at 200% zoom, the message and action remain readable without horizontal scrolling.
- [ ] When the first project is created, the normal list replaces the empty state.
- [ ] Filtering a nonempty list to zero matches shows the existing no-results state, not “No projects yet.”
## Scope and technical context
Reuse the current project-list components, permission checks and creation flow. No new permission, navigation redesign or new project form. Use existing design tokens. Dependency: design owner confirms the exact text and existing error/loading behavior before implementation.
## Verification
Check zero projects, one project, filtered zero results, denied create permission, loading and errors. Record keyboard, screen-reader and narrow-layout observations with the issue.Before handoff
- [ ] Are empty, loading, error and filtered states separate?
- [ ] Is behavior specified for each permission level?
- [ ] Are keyboard, focus and narrow-layout checks included?
- [ ] Are copy, scope and existing components clear?
What SpecBot contributes
SpecBot can flag missing states, scope and acceptance criteria. It cannot inspect the rendered UI, run accessibility checks or approve the design. A score is advisory, not proof that implementation will succeed. Correct the issue using facts the owner confirms, then review it again if your workspace allows rechecks. Rechecks use the shared monthly allowance.
Install SpecBot in Linear to review your next issue. No meeting or demo required. Review the workspace settings after installation; automatic comments may be enabled.