---
id: AGD-0054
ticket: pbs-lsp-diagnostics-ux
title: PBS LSP Diagnostics UX
status: open
created: 2026-07-15
resolved:
decision:
tags: [studio, lsp, vscode, compiler-pbs, editor, diagnostics, ux]
---

## Pain

Domain owner: `studio/lsp`

PBS diagnostics reach VS Code, but the editor experience can still be hard to act on when ranges, related information, severity, and phase context are too generic.

## Context

The LSP maps compiler diagnostics to LSP diagnostics. Compiler diagnostics include phase/code/message/range in several paths, but not all editor-friendly fields are consistently exposed.

## Open Questions

- [ ] Which diagnostics need better ranges or related information first?
- [ ] Should diagnostic source include compiler phase, frontend, or both?
- [ ] What structured diagnostic metadata is needed for future quick fixes without coupling UI to text messages?

## Options

### Option A - Mapper-only UX improvements

- **Approach:** Improve LSP diagnostic mapping using existing diagnostic fields.
- **Pro:** Quick improvements to source, severity, and display consistency.
- **Con:** Cannot add missing related spans or repair metadata that compiler diagnostics do not expose.
- **Maintainability:** Good for presentation-only changes.

### Option B - Structured diagnostic contract

- **Approach:** Extend compiler diagnostics with editor-facing metadata such as phase, related locations, stable quick-fix hints, and refined ranges.
- **Pro:** Enables better diagnostics and future code actions without parsing message text.
- **Con:** Requires compiler/core diagnostic API changes.
- **Maintainability:** Strong as the foundation for quick fixes and richer UX.

## Tradeoffs

Some improvements belong in the LSP mapper, but the most valuable changes require structured information at diagnostic creation time.

## Recommendation

Prefer Option B as the target, with mapper-only cleanup allowed for low-risk display fixes.

## Discussion

This agenda should inform code actions before quick fixes become broad.

## Resolution

Ainda em aberto.

## Next Step

Inventory high-frequency diagnostics and identify which need better ranges, related information, or repair hints.