Skip to main content

When 92% means different things

A UX writing case study on strings that state their own context in a plain-text interface.

Sweepy is a terminal-based job-search tool. The interface draws with box-drawing characters and colored text, and it reads keyboard input. An explanation has to live in the text itself, because a tooltip has nowhere to appear. The launchpad clips its status line at the frame edge rather than wrapping. A string either finishes inside the width or loses its ending.

One rule came out of that. Every string states its own context. Score labels state who wrote the number. Status copy follows the same discipline, from the launchpad's bottom line down to each prompt's format hint. The score is the hard case, because a percentage looks informative regardless of whether the reader knows how the tool produced it.

Two percentages, two questions​

Sweepy scores a posting against a resume in two different ways.

The first is the deterministic scorer, and every sweep runs it. sweepy opens the launchpad, and START SWEEP scores every card the sweep finds. sweepy --run repeats the last saved profile without opening the wizard. This pass compares two documents. It counts shared words between the resume and the posting, blending requirement overlap at 60% with keyword overlap at 40%, then scaling the result by resume.keywords_weight. A term counts only when it appears on both sides. The scorer never reasons about whether the reader could do the job.

The second is an agent assessment, available through the Model Context Protocol (MCP). An agent reads the parsed resume and the posting together, then reasons about how well the reader fits the role. It submits its own percentage through submit_judgments.

A shared-word count and an agent's judgment answer different questions. A count of shared words measures overlap, not fit, so the label has to name the writer. The count reports how much text the resume and the posting share. The agent judges how well one person suits one job. A resume can restate a posting word for word and still describe a weak fit. A resume in other vocabulary can describe a strong one. The word count spots the first case and misses the second, and the agent can weigh both.

The card shows one score. The most recent writer sets it, and an assessment re-ranks the report around the new value. The judgment replaces the deterministic score instead of sitting beside it. A bare percentage hides which of the two the reader has.

The copy had to state the writer inside the badge line, before the reader opens a listing. The rest of the interface follows the same rule.

From launchpad to results​

The flow runs launchpad → setup wizard → sweep → results. When a sweep outlasts the client's tool-call limit, it hands off to a pollable status that stays live until the run finishes.

Cards 3 through 8 follow that order. Card 2 covers the score, which exists only after a sweep ends and is the case the rest of the page builds toward. Card 1 states the problem, and card 9 states the constraint behind every string between them.

The frame width clips long strings​

The terminal sets the terms. Text is the only layer that explains anything, and the frame clips whatever runs long. An error has to state the problem and the fix in the same string. The reader can't leave the line to read another one.

The strings pay for their own context. Could not parse salary %r. Enter a number like 65000, 65,000, or 65k. reports what failed and what to type instead, with %r replaced by the rejected entry. Current profile: none loaded / build one to start does the same for a missing profile. A GUI could put the second half of either sentence in a tooltip. Here the line includes both halves.

The label as the only explanation​

The score label states who wrote the number. The docs put it plainly: "A MATCH card reflects judgment. A KEYWORD OVERLAP card reflects shared words." One label prints on a card beside one score. The reader knows which claim they have before opening the listing.

Each word also tells the reader what kind of comparison produced the figure. KEYWORD OVERLAP reports on two documents. MATCH reports on a person and a job. A reader who expects the two numbers to line up misreads one of them.

The label tracks the writer, not the interface. An agent can submit a judgment without a percentage. That card still reads KEYWORD OVERLAP, because the sweep wrote that number. The execution path lives outside the card. The report filename marks an MCP run with mcp, and the log header prints the execution method.

Tile naming follows the same rule. BUILD PROFILE states the action, and its subtitle, Set up your job search, drops the internal term for the reader's goal. LOAD PROFILE says Open a search you saved, which describes what the tile does.

What I wrote and how I checked it​

Role: sole writer of the product strings this case study quotes. Wrote the launchpad subtitles and the wizard prompts, then the progress messaging and the validation copy. The score-provenance labels and the MCP handoff message that a client relays came last. Directed the build with Copilot and Gemini, under repository-level agent guidelines and a CI quality gate. Verified the literal product strings against the Sweepy source.

Calibrate trust, then act​

A reader should calibrate trust before acting on a score and tell what the system is doing while they wait. The interface can't explain how Sweepy produced a number or how long a process takes. The label and status strings explain it in the fewest words, in a form that works without visual affordances.

The fifteen prompts in order​

The wizard runs fifteen steps. The fifteen top-level prompts appear in order, and the yes-or-no questions render as a yes/no selector.

Wizard prompts
? What is your name?
>

? What job titles are you looking for?
(Separate multiple titles with a comma)
>

? Where do you want to work? (City, State):
>

? Do you want to see remote-only roles? (Y/n)

? Do you want to include hybrid roles? (Y/n)

? What is the path to your resume PDF?
>

? What is your minimum target salary? (Leave blank to skip):
>

? Which boards do you want to search? Pick from any engine; downloaded engines are labeled.

? Do you want to add custom platforms or ATS domains? (Y/n)

? Enter must-have skills or keywords to prioritize
(comma-separated, leave blank to extract from resume):
>

? What export formats do you want?
[x] PDF Report
[x] CSV Spreadsheet
[ ] JSON Data

? Add job-tracking columns to the CSV? (date applied, status, interview stage,
offer, follow-up date, contact, notes) (Y/n)

? Do you want to configure multiple resume tracks
(e.g. Tech Writer vs UX Writer)? (Y/n)

? Do you have a portfolio, writing samples, or case studies to submit
with applications? (Y/n)

? Enable debug logging? (Logs are saved under logs/ in the application
directory): (Y/n)

Where to verify the strings​