Steer agents toward actionable platform feedback content

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:

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(' '),
 	)
 

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',
@@ -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)

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.
 
 Kody repository (for contributors): https://github.com/kentcdodds/kody