Quick labels: inconsistent across newer features, and a highlight can't be both labelled and commented

Open
  • Is something wrong?
#2,626 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
38/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
typescript
Domain
frontend

Research direction

Start by reading the named entry points: sharing.ts, parser.ts (formatDraftAnnotationsForAsk), packages/inbox/attachments.ts, packages/shared/feedback-archive.ts, and quickLabels.ts. The issue asks whether to change the annotation model so a highlight can combine a comment with a quick label or deletion, and to align label tips and 👍 names across exports. First resolve that design question, then define and update the model and export format; done means those combinations and details are represented consistently.

Written by the indexing model from the issue text.

Description

The Quick Label feature seems to have drifted, and become messy across the features added since
#268. Here's what I found:

  • The label's tip only reaches the agent from the main feedback export. Three other places
    drop it:
    • Share links. The link carries the label flag but not the tip, so a label from a
      shared review exports without its instruction (sharing.ts).
    • "Ask" about draft annotations. A label becomes one line, label "🔍 Verify this" on "…",
      with no tip (formatDraftAnnotationsForAsk in parser.ts).
    • Inbox message comments. They give a label its [🔍 Verify this] heading but no tip
      (packages/inbox/attachments.ts).
  • The feedback archive's structured record drops the label flag. index.jsonl keeps the
    annotations as data, but FeedbackAnnotationRecord has no isQuickLabel or tip field. In the
    data, a label is just a comment whose text is 🔍 Verify this. Only the feedback text still shows
    it as a label (packages/shared/feedback-archive.ts).
  • The 👍 has two names. In the ⚡ picker it is "Nice approach". The standalone button on the
    toolbar, the HTML pinpoint composer and the image lightbox is "Looks good" (quickLabels.ts).

These came up when I wanted to add a quick-label menu to the comment box, so that a label and a
comment could be used together or separately. If the delete button moved into the comment box
too, it would save extra clicks and streamline the process: select, then comment, label, mark for
deletion, or any mix of them, all in one place.

The problem I ran into with doing that cleanly is that Plannotator is structured to make you choose
between a comment, a label and a deletion. Each one is its own annotation:

  • A comment holds your text.
  • A label is a comment whose text is the label, plus a flag and the label's tip. It can't hold
    your own words as well.
  • A deletion is a separate type that exports as "Remove this" and the quoted text, with no
    comment.

So putting a label on a comment means either replacing the comment or making two annotations on
the same text.

My question is: is that restriction really needed? A deletion is really a special quick label,
one that also strikes the text out. So a highlight could be any of:

  • a deletion, with or without a comment;
  • a quick label, with or without a comment;
  • a plain comment.

A deletion and a quick label wouldn't go on the same highlight.

For example:

## 1. (line 12) [🔍 Verify this] Feedback on: "retries a failed payout three times"
> This seems like an assumption. Verify by reading the actual code before proceeding.
> Is it really three? The config says five.

## 2. (line 20) Remove this
```
Fall back to the legacy payout queue.
```
> The legacy queue was removed last month.

One label per highlight seems enough to me, but I'm not against allowing more than one, say
🔍 Verify this and 🚫 Out of scope together.

I saw that #1693 kept a 👍 out of the comment box, since it "doesn't exist elsewhere", and that
#1712 brought it back only where no toolbar shows. So I'd rather ask before building anything. Is
this a direction you'd take? If it is, I'm happy to work out the model change and the export
format in a PR.

Drafted by Ben's agent at his request.

Dominant language
TypeScript
Stars
8.7k
Forks
649
Avg merge
8h 40m
Merged PRs (30d)
786

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from backnotprop/plannotator

All issues in backnotprop/plannotator

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.