docs(agent): add the feedback and feedback-invite recipes

[thecodedrift]

Stack (root → tip):

• docs(openspec): propose qualitative survey feedback via PostHog surveys #341
  • feat(scaffold): migration 0007 ignores .taskless/.tmp-* scratch files #342
    • feat(feedback): add feedback send/dismiss, the survey constants, and the cadence store #343
      • ➡️ docs(agent): add the feedback and feedback-invite recipes #344 (you are here)
        • feat(agent): append the feedback survey invite to surveyed recipes #345

Slice 3 of 4 of qualitative-survey-feedback (stacked on #343). Prose-heavy by design; the code change is three registrations.

What

• src/agent/feedback.md (topic v1): the agent is the respondent. verbatim is the user's reply untouched; goal, completed, workedWell, needsImprovement come from the agent's own account of the session. One follow-up question at most, and only when completed would otherwise be a guess. Writes .taskless/.tmp-feedback.json, runs feedback send --from … --json, cleans up. Embeds the payload schema via %(INPUT_SCHEMA)s.
• src/agent/feedback-invite.md (topic v1): the fragment slice 4 appends after a served recipe's last section. The fixed sentence to put to the user, the decline rule (skip, silence, unrelated → feedback dismiss), the feedback door (agent feedback), and ask-once. Lives under src/agent/ so Vale and the cross-reference tests cover it; the gate renders it with header: false.
• TOPIC_INPUT_SCHEMAS gains feedback; both topics classified under INTERNAL_TOPICS with the reason recorded; the prompts source-level allowlist admits ../schemas/feedback (a leaf: zod plus pure-data constants). The build's assert-prompts-graph passes.

Tests

feedback-recipes.test.ts: agent feedback opens with its header and renders every schema key and every completed choice; both commands render by the supplied invocation; the invite renders header-less, starts at ## Before you finish, carries the exact ask sentence (unwrapped from the blockquote), names both doors, and states the decline rule. Existing suites cover header/topic agreement, dangling citations, hand-spelled invocations, Vale over the prose, and prompts export parity.

Refs #341

[thecodedrift]

@claude /review

[claude]

Claude finished @thecodedrift's task in 3m 57s —— View job

---

Review: docs(agent) feedback and feedback-invite recipes

Review mode: incremental — read 0 prior review thread(s) before reviewing. .prior-review.json contains only the triggering @claude /review comment itself; there are no prior review threads, reviews, or resolved/unresolved findings recorded, so this is the first review pass on this PR.

• Read .prior-review.json
• Fetched PR diff (gh pr diff 344) and metadata
• Read src/agent/feedback.md and src/agent/feedback-invite.md in full
• Cross-checked prose against implementation: src/commands/feedback.ts, src/schemas/feedback.ts, src/survey/constants.ts, src/prompts/recipes.ts, src/prompts/index.ts, src/commands/agent.ts
• Verified test expectations in test/feedback-recipes.test.ts and the updated allowlist in test/prompts.test.ts against the actual rendering pipeline
• Posted findings

Assessment: no findings. This is a prose-heavy, low-risk slice as described — the only executable changes are the three registrations (INTERNAL_TOPICS, TOPIC_INPUT_SCHEMAS, the source-import allowlist), and they all check out:

• feedback / feedback-invite are correctly added to INTERNAL_TOPICS in src/prompts/index.ts, matching the on-disk recipe files and satisfying the TOPICS ∪ INTERNAL_TOPICS == canonicalRecipeTopics() completeness test.
• TOPIC_INPUT_SCHEMAS.feedback wires %(INPUT_SCHEMA)s in feedback.md to the real inputSchema in src/schemas/feedback.ts — the required/optional fields and COMPLETED_CHOICES enum the recipe describes match the schema exactly.
• The ../schemas/feedback addition to the source-level import allowlist in test/prompts.test.ts is accurate: it imports only zod and ../survey/constants, which is pure data with no further imports, so it doesn't smuggle the CLI runtime into the Worker-safe prompts bundle.
• The fixed ask sentence, the decline rule, and the two command doors (agent feedback / feedback dismiss) in feedback-invite.md render exactly as the new tests expect (manually traced through sprintf substitution and stripHeader).
• The feedback.md Errors table (INVALID_INPUT only) matches commands/feedback.ts's sendCommand, which is in fact the only failure path that produces the --json envelope.
• Header format (# Topic: <name> (CLI v%(CLI_VERSION)s / topic v1)) matches the convention used by existing recipes (create-remote-rule.md, improve-rule.md).
• No CLAUDE.md rule (import ordering, direct-vs-barrel imports, library types) is violated by the small code changes in recipes.ts/index.ts.

One non-blocking observation, not a bug: feedback.md states "You reach it from the invite at the end of an authoring or onboarding recipe," but the invite gate itself (the code that appends feedback-invite and emits survey shown) isn't wired up yet — confirmed by grepping for survey shown, which doesn't exist anywhere in src/. That's expected given this is slice 3 of 4 and the gate is slice 4 (#345); flagging only so it's clear this was checked rather than missed.

[thecodedrift]

Re: @claude[bot] — "Review: docs(agent) feedback and feedback-invite recipes … Assessment: no findings."
#344 (comment)

Read; no findings to act on. The observation that the gate is not yet wired is correct and expected: it lands in #345, the next slice up.

— AI Coding Agent