From ce729e98884aecde10c1d02343fe4dc01aa93315 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 19 Jul 2026 20:50:31 +0000 Subject: [PATCH 1/2] Steer agents toward actionable platform feedback content Co-authored-by: Kent C. Dodds --- docs/guides/platform-friction.md | 31 +++++++++++++++++++ .../coding/kody-official-guide.ts | 4 +-- .../meta/meta-platform-feedback-submit.ts | 10 ++++-- .../worker/src/mcp/server-instructions.ts | 2 +- 4 files changed, 41 insertions(+), 6 deletions(-) diff --git a/docs/guides/platform-friction.md b/docs/guides/platform-friction.md index 00e5ceefc9..813991a9fb 100644 --- a/docs/guides/platform-friction.md +++ b/docs/guides/platform-friction.md @@ -130,6 +130,37 @@ category fits, while keeping the same approval and privacy rules. If the user declines or does not answer, continue the main task without submitting feedback. +## Write feedback admins can act on + +Submit one issue per call. Unrelated problems get separate submissions. Each +account already has the 10-per-24h and 100-active limits above, so prioritize +the most useful reports. + +Write a summary that names the affected area and the specific symptom or need so +an admin can triage from the list view alone (list results intentionally show +only the summary). Good: +`package_save rejects README-only updates with a misleading validation error`. +Vague: `packages are broken`. + +In details, capture the firsthand context you uniquely have while it is still in +the conversation: + +- what the user was trying to accomplish +- exact capability, package, or guide names and non-secret inputs involved +- minimal reproduction steps +- expected vs actual behavior +- verbatim error text quoted as text +- frequency (always / intermittent, plus conditions) +- impact (blocked vs degraded, and any workaround plus its cost) + +For `suggestion` feedback, lead with the underlying problem and the cost of the +current workaround; present a proposed change as one possible approach rather +than the requirement. Separate observed facts from diagnosis: label suspected +root causes as suspicion. + +Keep omitting secrets and unrelated private content. Quote the relevant excerpt +rather than pasting long transcripts or logs. + ## Suggested phrasing Use concise language: diff --git a/packages/worker/src/mcp/capabilities/coding/kody-official-guide.ts b/packages/worker/src/mcp/capabilities/coding/kody-official-guide.ts index b15285825b..032f6d9865 100644 --- a/packages/worker/src/mcp/capabilities/coding/kody-official-guide.ts +++ b/packages/worker/src/mcp/capabilities/coding/kody-official-guide.ts @@ -81,7 +81,7 @@ export const kodyOfficialGuideCatalog = { file: 'platform-friction.md', title: 'Kody platform friction guide', summary: - 'Use for meaningful Kody friction, bugs, poor experiences, or suggestions: show the exact proposal and account-identity notification disclosure before asking for explicit approval.', + 'Use for meaningful Kody friction, bugs, poor experiences, or suggestions: show the exact proposal and account-identity notification disclosure before asking for explicit approval, and write one actionable issue per submission (repro steps, expected vs actual, impact).', }, } as const @@ -158,7 +158,7 @@ const guideFieldSchema = z '`package_invocation_token_setup`: /account/package-invocation-tokens/new setup URL shape, owner-scoped /@:username/api/package-invocations invocation route shape, query params, and bearer-token safety policy for external package invocation clients.', '`package_service_pattern`: package-native long-lived service architecture built on package services and package app realtime.', '`package_subscriptions`: package-owned event subscriptions, package_subscriptions_list discovery, metadata-first email payloads, and consent-gated admin-only platform.feedback.submitted notifications with untrusted text, submitter identity, and an admin deep link.', - '`platform_friction`: choose an inline fix, an approved memory workflow, or attributed platform feedback after showing the exact proposal and notification disclosure and receiving explicit user approval.', + '`platform_friction`: choose an inline fix, an approved memory workflow, or attributed platform feedback after showing the exact proposal and notification disclosure and receiving explicit user approval, writing one actionable issue per submission.', ].join(' '), ) diff --git a/packages/worker/src/mcp/capabilities/meta/meta-platform-feedback-submit.ts b/packages/worker/src/mcp/capabilities/meta/meta-platform-feedback-submit.ts index bf9b111059..071d047971 100644 --- a/packages/worker/src/mcp/capabilities/meta/meta-platform-feedback-submit.ts +++ b/packages/worker/src/mcp/capabilities/meta/meta-platform-feedback-submit.ts @@ -28,20 +28,24 @@ export const metaPlatformFeedbackSubmitCapability = defineDomainCapability( inputSchema: z.strictObject({ category: z .enum(platformFeedbackCategories) - .describe('Stable feedback category.'), + .describe( + 'Stable feedback category: "bug" for reproducible defects, "friction" for capability/guide/package text that caused a wrong turn, "experience" for a poor overall experience, "suggestion" for a problem-first improvement idea, "other" when nothing fits.', + ), summary: z .string() .trim() .min(1) .max(200) - .describe('Concise feedback summary (1–200 characters).'), + .describe( + 'Specific, scannable summary naming the affected area and symptom or need (1–200 characters); admins triage from this line alone, so avoid vague summaries like "search is broken".', + ), details: z .string() .trim() .min(1) .max(8000) .describe( - 'Feedback details (1–8000 characters). Do not include secrets or unrelated private content.', + 'Feedback details (1–8000 characters), one issue per submission: goal context, exact capability or package names, minimal reproduction steps, expected vs actual behavior, verbatim error text, frequency, impact, and any workaround. Do not include secrets or unrelated private content.', ), user_confirmed: z .literal(true) diff --git a/packages/worker/src/mcp/server-instructions.ts b/packages/worker/src/mcp/server-instructions.ts index 44fe6eff60..237dd73d86 100644 --- a/packages/worker/src/mcp/server-instructions.ts +++ b/packages/worker/src/mcp/server-instructions.ts @@ -70,7 +70,7 @@ Conventions: - Jobs, workflows, sessions, services, values, storage, and the other capability groups below are individual capabilities: discover them with \`search\`, whose entity detail includes each capability's exact call shape. - Memory writes are verify-first: run \`meta_memory_verify\` before \`meta_memory_upsert\` or \`meta_memory_delete\`. - User-specific MCP instructions: \`meta_get_mcp_server_instructions\` / \`meta_set_mcp_server_instructions\` (signed-in users). Updates apply to **new** MCP sessions. -- For meaningful or recurring Kody friction, bugs, poor experiences, or suggestions, load \`coding_guide_get({ guide: "platform_friction" })\`. Show the exact proposed feedback and explain the attributed admin-notification disclosure before asking; call \`meta_platform_feedback_submit\` with \`user_confirmed: true\` only after explicit approval of that exact text. +- For meaningful or recurring Kody friction, bugs, poor experiences, or suggestions, load \`coding_guide_get({ guide: "platform_friction" })\`. Show the exact proposed feedback and explain the attributed admin-notification disclosure before asking; call \`meta_platform_feedback_submit\` with \`user_confirmed: true\` only after explicit approval of that exact text. Write one actionable issue per submission: specific summary, repro steps, expected vs actual, impact. Kody repository (for contributors): https://github.com/kentcdodds/kody From 8dbc4962de5b2f4a9d12937eb6827a8bc7462178 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 19 Jul 2026 20:59:42 +0000 Subject: [PATCH 2/2] Move feedback discovery from server instructions to submit capability description Co-authored-by: Kent C. Dodds --- .../src/mcp/capabilities/meta/meta-platform-feedback-submit.ts | 2 +- packages/worker/src/mcp/server-instructions.ts | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/worker/src/mcp/capabilities/meta/meta-platform-feedback-submit.ts b/packages/worker/src/mcp/capabilities/meta/meta-platform-feedback-submit.ts index 071d047971..f72cfa2f80 100644 --- a/packages/worker/src/mcp/capabilities/meta/meta-platform-feedback-submit.ts +++ b/packages/worker/src/mcp/capabilities/meta/meta-platform-feedback-submit.ts @@ -14,7 +14,7 @@ export const metaPlatformFeedbackSubmitCapability = defineDomainCapability( { name: 'meta_platform_feedback_submit', description: - 'Submit platform feedback only from an interactive MCP agent flow after showing the user the exact proposed summary and details, asking first, and receiving explicit approval. The exact approved summary and details plus the account user id, username, and email may be delivered immediately to deployment admins through admin-configured notification integrations such as Discord. Copies already delivered outside Kody, including Discord messages, may remain after Kody account deletion under the deployment operator’s retention and deletion controls. Non-interactive package code and package apps cannot submit. Do not include secrets or unrelated private content.', + 'Submit platform feedback only from an interactive MCP agent flow after showing the user the exact proposed summary and details, asking first, and receiving explicit approval. Load `coding_guide_get({ guide: "platform_friction" })` first for the approval flow and content guidance. The exact approved summary and details plus the account user id, username, and email may be delivered immediately to deployment admins through admin-configured notification integrations such as Discord. Copies already delivered outside Kody, including Discord messages, may remain after Kody account deletion under the deployment operator’s retention and deletion controls. Non-interactive package code and package apps cannot submit. Do not include secrets or unrelated private content.', keywords: [ 'platform feedback', 'friction', diff --git a/packages/worker/src/mcp/server-instructions.ts b/packages/worker/src/mcp/server-instructions.ts index 237dd73d86..10bdece4c4 100644 --- a/packages/worker/src/mcp/server-instructions.ts +++ b/packages/worker/src/mcp/server-instructions.ts @@ -70,7 +70,6 @@ Conventions: - Jobs, workflows, sessions, services, values, storage, and the other capability groups below are individual capabilities: discover them with \`search\`, whose entity detail includes each capability's exact call shape. - Memory writes are verify-first: run \`meta_memory_verify\` before \`meta_memory_upsert\` or \`meta_memory_delete\`. - User-specific MCP instructions: \`meta_get_mcp_server_instructions\` / \`meta_set_mcp_server_instructions\` (signed-in users). Updates apply to **new** MCP sessions. -- For meaningful or recurring Kody friction, bugs, poor experiences, or suggestions, load \`coding_guide_get({ guide: "platform_friction" })\`. Show the exact proposed feedback and explain the attributed admin-notification disclosure before asking; call \`meta_platform_feedback_submit\` with \`user_confirmed: true\` only after explicit approval of that exact text. Write one actionable issue per submission: specific summary, repro steps, expected vs actual, impact. Kody repository (for contributors): https://github.com/kentcdodds/kody