Steer agents toward actionable platform feedback content

[kentcdodds]

Why

The platform-feedback steering (the platform_friction guide, meta_platform_feedback_submit schema descriptions, and MCP server instructions) thoroughly covers consent, attribution, and privacy, but says nothing about what makes the feedback content itself useful to triage. Research on high-quality product feedback (Mozilla bug-writing guidelines, OpenTelemetry good-issues guide, Atlassian product-discovery guidance, NN/g task-context research) converges on: one issue per submission, a specific scannable summary, goal context, minimal repro steps, expected vs actual, verbatim errors, frequency, impact/workaround cost, and problem-first framing for suggestions. Agents are uniquely positioned to capture that firsthand context while it is still in the conversation — but nothing told them to.

What changed

• docs/guides/platform-friction.md: new ## Write feedback admins can act on section covering one issue per submission, summary quality (with a good-vs-vague example, noting admins triage from the summary-only list view), a details checklist (goal context, exact capability names, repro steps, expected vs actual, verbatim errors, frequency, impact/workaround), problem-first framing for suggestion feedback, fact-vs-suspicion labeling, and excerpt-over-transcript quoting.
• meta-platform-feedback-submit.ts: the category, summary, and details field descriptions now steer content quality (when to pick each category; specific scannable summary; per-issue details checklist), and the capability description points at coding_guide_get({ guide: "platform_friction" }) for the approval flow and content guidance. No handler or shape changes.
• kody-official-guide.ts: the platform_friction catalog summary and guide enum description now also advertise the one-actionable-issue content bar.
• server-instructions.ts: the platform-feedback bullet is removed from the base server instructions. Server instructions hold a high bar (workflows and cross-tool conventions, per docs/contributing/mcp-server-patterns.md); feedback discovery now lives on the capability surfaces themselves — the meta domain description, the submit capability's description/keywords, and the coding_guide_get guide catalog — which agents hit through search and tool listings.

No runtime behavior, schema shape, validation, or storage changes — text-only steering.

System recap — extends existing primitives (medium risk, prompt-surface text only)

Mode: recap · Base: main @ 84952ee3 · Head: 8dbc4962

Classification: extends — the change edits agent-facing contract text (schema descriptions, guide body) on existing primitives and removes one bullet from the base server instructions. No runtime behavior, schema shape, or storage changes.

Primitives touched

Primitive	Group	Impact
platform-feedback	assistant	extends — capability description + category/summary/details describe() text
capability-registry	assistant	extends — coding_guide_get platform_friction summary/describe text
mcp-server	surfaces	extends — platform-feedback bullet removed from base server instructions

System map

An agent discovers the feedback flow from the submit capability and guide catalog descriptions (no longer from server instructions), loads the guide body from docs/guides/platform-friction.md on main, and then calls the unchanged submit handler.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).

flowchart LR
	mcpServer["mcp-server<br/>MCP endpoint (/mcp)"]:::extended
	capabilityRegistry["capability-registry<br/>Capability registry"]:::extended
	platformFeedback["platform-feedback<br/>Platform feedback"]:::extended
	guideDoc["docs/guides/platform-friction.md<br/>guide body (fetched from main)"]:::extended
	mcpServer -->|"platform-feedback bullet removed from instructions"| capabilityRegistry
	capabilityRegistry -->|"coding_guide_get platform_friction summary"| guideDoc
	guideDoc -->|"new: Write feedback admins can act on section"| platformFeedback
	capabilityRegistry -->|"submit description + category/summary/details describe() text"| platformFeedback
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Testing

• npm run validate (format:check, lint, typecheck, unit tests, Playwright E2E, MCP E2E) locally.

  

Summary by CodeRabbit

• Documentation
  • Added guidance for writing clear, actionable platform feedback.
  • Feedback instructions now emphasize one issue per submission, concise summaries, reproducible details, expected versus actual behavior, and relevant error messages.
  • Clarified privacy expectations, including excluding secrets and unrelated private content.
• Improvements
  • Updated feedback submission guidance to require showing the exact proposal and account-identity disclosure before requesting approval.
  • Clarified how approved feedback may be shared with deployment administrators and retained after account deletion.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2c9a5e95-5220-44d4-a9a4-6586e9ec81da

📥 Commits

Reviewing files that changed from the base of the PR and between 84952ee and 8dbc496.

📒 Files selected for processing (4)

• docs/guides/platform-friction.md
• packages/worker/src/mcp/capabilities/coding/kody-official-guide.ts
• packages/worker/src/mcp/capabilities/meta/meta-platform-feedback-submit.ts
• packages/worker/src/mcp/server-instructions.ts

💤 Files with no reviewable changes (1)

• packages/worker/src/mcp/server-instructions.ts

---

📝 Walkthrough

Walkthrough

Platform feedback guidance now defines actionable issue content, expands submission metadata descriptions, updates approval and disclosure instructions, and removes the corresponding approval-flow bullet from the base MCP server instructions.

Changes

Platform feedback workflow

Layer / File(s)	Summary
Actionable feedback content docs/guides/platform-friction.md, packages/worker/src/mcp/capabilities/meta/meta-platform-feedback-submit.ts	Documentation and schema descriptions now require one actionable issue with relevant context, reproduction steps, expected versus actual behavior, and exclusions for secrets or unrelated content.
Approval and guide instructions packages/worker/src/mcp/capabilities/coding/kody-official-guide.ts, packages/worker/src/mcp/capabilities/meta/meta-platform-feedback-submit.ts, packages/worker/src/mcp/server-instructions.ts	Guide and capability descriptions now specify showing the exact proposal and account-identity disclosure before approval, while the base server instruction no longer contains the prior approval-flow bullet.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• kentcdodds/kody#660: Adds related platform_friction guide usage in MCP instructions and guide registration.
• kentcdodds/kody#783: Introduces the user-confirmed, consent-gated platform-feedback approval contract referenced by these updates.
• kentcdodds/kody#785: Expands the platform feedback submission contract with approved feedback, disclosure, identity snapshots, and admin review handling.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: improving platform feedback guidance so agents produce more actionable submissions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/feedback-quality-steering-85c2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔎 Preview deployed: https://kody-pr-789.kody-a99.workers.dev

Worker: kody-pr-789
D1: kody-pr-789-db
KV: kody-pr-789-oauth-kv

Mocks:

• cloudflare: https://kody-pr-789-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-789-mock-cloudflare)