[tylercschneider]

One Sentence Summary

The flow owner can fix a drawing from warnings written as plain sentences, without reading step ids or internal codes.

ACs Covered

• Each warning names the step by the name it shows on the canvas, never by its id.
• Each warning is a sentence saying what is wrong.
• Each warning says what to do to clear it.
• No warning shows an underscore.
• A step type can give each of its settings a one-sentence explanation that shows under that setting in the step's settings.

Decision Log

Where should the plain sentence for a canvas warning be worked out?

A new display class on the server words each violation and the canvas payload carries the sentence beside the problem symbol, rather than adding a field to Violation that host tests compare by equality or wording it in the browser, which cannot read setting labels.

What should a warning call a step that has no name of its own?

It uses the step type's name, even where the card heading shows the id, rather than the id, because the issue says a warning never names a step by its id.

Should a warning keep an underscore that an admin typed into a step name or an answer value?

Every underscore in a sentence becomes a space, rather than leaving typed ones as they are, because the issue says no warning shows an underscore.

How should a step type's setting explanations be carried so a host can later give its own?

Each is declared on the setting and sent per step type in the canvas palette, keyed by setting and by list entry setting, so a later host explanation can replace it where that palette entry is built, rather than joining it to the field type or the input.

What should a warning say for a problem symbol that has no sentence of its own?

It names the step and the problem in words with no instruction, rather than raising an error that stops the canvas opening or guessing at a fix.

Code Example

StepType.define(:note) { setting :tag, type: :string, explanation: "Groups the answers." }

Out of Scope

• The explanations for the Pipelines hub's own step settings are written in Unit 2.3.

Ticket Billed Against

Not specified.

Tokens Used

• Input: 100
• Output: 67,262
• Cache read: 5,971,952
• Cache write: 235,552
• Total: 6,274,866

Effort

• Sessions: 0
• Prompts: 0
• Words typed: 0
• Pasted blocks: 0
• Words pasted: 0
• Questions answered: 0
• Interruptions: 0
• Rejected tool calls: 0
• Claude working time: 0m
• Your active time: 0m

Time Spent

• Total: 9m
• Waiting on the owner: 0m
• Model time: 0m
• Worktree setup: 1m
• Reading: 1m
• Test-first cycles: 2m
• Commits: 0m
• Ticking criteria and recording decisions: 2m
• Full-suite checks: 0m
• Other tool calls: 3m
• pr-scribe: 0m

Closes #112

---

Generation Metadata

Scribe: pr-scribe 9d1ee89
Rules: pr-body 9d1ee89, draft-reading 0d470c5, writing-style c3c2f61
Model: claude-sonnet-5-5, cc 2.1.312