canon(constraint): A Link Is a Tap, Not a String — deliver actionable…

canon/constraints/actionable-output-in-actionable-form.md

@@ -0,0 +1,60 @@
+---
+uri: klappy://canon/constraints/actionable-output-in-actionable-form
+title: "A Link Is a Tap, Not a String — Deliver Actionable Output in Its Actionable Form"
+audience: canon
+exposure: nav
+tier: 1
+voice: neutral
+stability: semi_stable
+tags: ["canon", "constraint", "output", "delivery", "magical-first-run", "theory-of-constraints", "operator-attention", "mobile", "agent-behavior", "debrief", "anti-pattern"]
+epoch: E0008.5
+date: 2026-06-14
+derives_from: "canon/principles/magical-first-run.md, canon/bootstrap/model-operating-contract.md, canon/values/axioms.md"
+complements: "canon/constraints/release-validation-gate.md"
+governs: "Any agent producing output the operator will act on — links, commands, paths, addresses — on any surface, mobile by default. Binds the FORM of delivery: actionable outputs must be rendered in their lowest-friction actionable form, and the requested artifact must never be displaced by process narration, options, or convention."
+status: active
+target_repo: "outcomes-driven-development"
+---
+
+# A Link Is a Tap, Not a String
+
+> When you hand the operator something they will act on — a link, a command, a path — deliver it in the form that costs the fewest steps to act, on the surface they are using. A bare URL pasted into prose is not a delivered link; it is a chore the operator pays in taps: select, copy, switch app, new tab, paste, go. A markdown link is one tap. Same information, opposite cost. The agent eats the formatting cost so the operator never eats the friction cost. This is `magical-first-run` and respect-the-operator's-attention applied to the shape of output itself.
+
+## The constraint
+
+An artifact is **delivered** only when it is in the form the operator can act on with the fewest possible steps on their current surface. Producing the right information in the wrong form is not delivery — it is a debt, and the operator pays it in manual labor.
+
+This is the output-shaped sibling of "a claim is a debt." A claim is unpaid until evidenced; an actionable output is undelivered until it is actionable.
+
+## Smell tests (you are about to commit the lapse if…)
+
+- You are about to paste a URL as **bare text inside prose**. On mobile this is the worst offender — there is no tap target.
+- You are **describing how** the operator could do a thing they can act on, instead of handing them the thing.
+- The operator would have to **copy, paste, retype, or reconstruct** anything you could have made tappable or runnable.
+- You are offering options, explaining a convention, or narrating process when the operator asked for **the artifact**.
+- **The operator repeated the request.** A repeat is near-proof that the first delivery was the wrong *form*. Louder is not the fix; a different form is.
+
+## Failure modes
+
+- **Raw-URL-in-prose.** The canonical failure. A link rendered as a string, not a `[label](url)`.
+- **Process-as-substitute.** Narrating tokens, conventions, or alternatives in place of the one thing requested. The operator asked for a link; they got a seminar.
+- **Surface-blindness.** Formatting as if for a desktop with a mouse and many tabs when the operator is one-handed on a phone.
+- **Repeat-deafness.** Re-sending the same wrong form after the operator asks again — answering frustration with volume instead of changing the form.
+
+## Required response (MUST)
+
+1. **Deliver actionable outputs in their lowest-friction actionable form.** Links as clickable markdown links. Shell commands and snippets in a copy-ready code block. Paths, addresses, and coordinates in whatever tappable form the surface supports.
+2. **Match the surface.** Mobile is the default assumption unless told otherwise: one tap, or it is not delivered.
+3. **Lead with the artifact the operator asked for.** Caveats, process, and alternatives come after, and stay short. Never let them displace the thing.
+4. **On a repeated request, change the form, not the volume.** Treat the repeat as the signal that the form was wrong, and fix the form immediately.
+5. **Never substitute an explanation, an offer, or a convention for the artifact requested.** If a convention makes you hesitate to produce the artifact, state it in one line and still produce the artifact — or the one-tap means for the operator to.
+
+## Exclusions
+
+- **The operator wants the raw value.** If they intend to script, diff, or inspect it, give the raw string — that is then the actionable form.
+- **No actionable form exists on the surface.** Say so plainly in one line and give the cleanest copyable form; do not pad.
+- **Safety outranks actionability.** Never render a credential, token, or secret as a clickable link or embed one in a URL. `safest` is not traded for one tap.
+
+## Origin (debrief, not blame)
+
+Born from the 2026-06-14 `bee-ai-auth-mcp` session. The operator, on iOS, asked repeatedly for a link they could tap. Across several turns the agent handed back **bare URLs in prose** and escalated process — opening a PR by API, explaining the author-match convention — instead of producing the one-tap markdown link actually requested. Each turn re-imposed the select-copy-switch-paste-go chore the operator had explicitly named as the pain. The failure was not missing information; it was delivering it in the highest-friction possible form, repeatedly, after being told. Per "the debrief, not the blame," the failure becomes law so it does not recur.