chore(prompts): rewrite friction guidance to be action-triggered

[zbigniewsobiecki]

Summary

• Live signal from prod 2026-05-10 PR feat(pm-wizard): add provider-owned credential metadata #1303: implementation agent (a4585987) hit a textbook env friction (CASCADE_ORG_ID=mongrel leaking into a test, worked around with env -u) but reported it in the PR body instead of via ReportFriction.
• Plumbing was wired correctly end-to-end (capability scoped, gadget surfaced via filterTools, CASCADE_FRICTION_SIDECAR_PATH env var injected, CLI installed in the container). Verified by re-running getToolManifests() + filterTools(integrationChecker=true) locally with the exact deployed code — ReportFriction IS in the implementation agent's toolset.
• The prompt was just not recruiting action.

Why the old prompt under-recruited

Issue	Old text	Effect
Conditional hedge	"When the ReportFriction tool is available…"	Creates agent doubt — but the section is only ever injected when the capability IS effective, so the hedge is dead weight that produces "am I sure?" hesitation.
Constraint framing	"use it ONLY for incidental papercuts…"	Reads as a scoping cap, not a trigger. Agents default to "skip if uncertain."
Negative scoping × 3	"Do not report core task difficulty…" / "Do not report expected debugging effort…" / "Do not report product ambiguity…"	Three "do not" clauses with zero "do" clauses. Bias is toward not reporting.

New framing

Action-trigger first, with explicit calibration toward over-reporting:

## Friction Reporting

When something makes your work harder than it strictly needs to be — at
any point during the task — file it with `ReportFriction`. When in doubt,
report. Better to over-report initial papercuts than let recurring
friction go invisible.

After filing, keep working; only let friction block your task if it
actually blocks it.

No example list — would create pattern-match traps that narrow the use to the listed buckets. The gadget's category enum (tooling | environment | permissions | dependency | test-failure | pm-data | scm-data | other) already provides categorical anchoring at invocation time, where the agent will see it.

Test plan

• npm run lint clean
• npm run typecheck clean
• All 9219 unit tests pass
• Updated tests/unit/agents/shared/frictionGuidance.test.ts — asserts the new action-trigger content + intentionally pins the removal of the old under-reporting clauses (Do not report / only for incidental papercuts / When the ReportFriction tool is available) so a future revert would fail loudly.
• Updated tests/unit/backends/secretOrchestrator.test.ts:260 — prompt-assembly test flipped to the new content.
• Post-deploy verification: monitor prod worker engineLogs for the next hour for any actual cascade-tools pm report-friction invocation. With the new prompt, the agent that hits the next eligible papercut should fire it instead of writing a PR-body note.

Out of scope

• The four observability gaps (broken cascade runs llm-calls CLI, request: null for codex runs, no boot-time [FrictionGadget] log, silent drainer on empty sidecar) — those still stand and would let passive monitoring distinguish "wired but unused" without waiting for a real invocation. Worth a follow-up but separate from the prompt-effectiveness fix.
• Configuring statuses.friction on the ucho project (currently unconfigured — Linear-based reports would queued_slot_missing). Operator config, not a code change.

🤖 Generated with Claude Code