galaxy/specs/APP-3773/PRODUCT.md

APP-3773: Image attachments in the feedback skill

Linear: https://linear.app/warpdotdev/issue/APP-3773/add-support-for-image-uploads-in-the-feedback-skill

Summary

When a user runs /feedback with one or more image attachments, the drafted GitHub issue reflects what's in those images, and the user is led through a simple flow that results in the images rendering inline on the filed issue. The first phase of this feature does not upload images from Warp itself; it uses the GitHub web UI's native drag-and-drop upload as the delivery path. Later phases may adopt first-party gh CLI attachment support or a Warp-hosted persistent image service. See "Future delivery paths" for what changes for the user under each alternative.

Problem

Today, attaching an image to a slash-command invocation silently drops the image before the skill's agent runs. The /feedback skill therefore files issues that make no reference to screenshots the user tried to attach, even though in-app feedback about visual bugs is one of the highest-value attachment use cases. Fixing this has two parts: the attachments must reach the skill's agent at all, and the drafted issue must end up with the images actually rendered on GitHub.

Behavior

1. When the user invokes the feedback skill (for example via /feedback) with one or more pending image attachments, the agent receiving the skill context sees those images as multimodal input, exactly as it would in a non-skill query.
2. The agent uses what it can see in the attached images when drafting the issue. At minimum, it describes the relevant visual content in the issue body (for example, in a "Problem" or "Actual behavior" section) so the report is coherent even if no image is attached to the final GitHub issue.
3. When one or more images are attached, the skill chooses the browser-based filing path over the gh issue create path, regardless of whether gh is installed and authenticated. This is the only behavior that differs from the no-attachments case at the filing step.
4. When zero images are attached, the existing filing behavior is unchanged: gh issue create is used when available, and the browser fallback is used otherwise.
5. In the browser path with images, the drafted issue body includes one visible placeholder per attached image, positioned in the artifacts/screenshots area of the body. Each placeholder is clearly a placeholder to a human reader (for example, a single line such as _Paste screenshot here_) so the user knows where to drop the file.
6. The skill's final agent-authored response to the user explicitly states that (a) the new-issue page has been opened in their browser, (b) they should paste or drag their attached image(s) into the body at the placeholder line(s), and (c) they should review and submit the issue to complete filing. It does not claim the issue has been filed until the user submits.
7. After the user drops or pastes an image into the issue body in the browser, the image renders inline in the filed GitHub issue using GitHub's standard user-attachments URL. Warp does not produce, host, or embed the image itself, and does not require any new backend.
8. When the drafted body is short enough to fit in the new-issue URL's prefill capacity, the body (including placeholders) is prefilled in the URL, and the user only needs to paste/drop images and submit.
9. When the drafted body exceeds the URL prefill capacity, the existing clipboard fallback applies: only the title is prefilled, the body is copied to the system clipboard, and the user is told (in the agent's response) to paste the body into the issue form first, then paste/drop their image(s) into the placeholder line(s), then submit.
10. When the system cannot open a browser (for example, a headless Linux session with no display server), the skill falls back to the gh issue create CLI flow. If gh is installed and authenticated, the issue is filed programmatically with the available text contents and a clear message informs the user that the browser could not be opened and that image attachments were not uploaded to the filed issue. If gh is also unavailable, filing fails with a clear error message that notes both failures. No image is silently lost without acknowledgement in either case.
11. No image bytes are written to disk by the feedback skill or its helper script. There is no temp-file folder, no cleanup requirement, and no privacy footprint beyond what already exists for the user's original attachment.
12. The user is never asked to re-select or rebrowse for their image. They paste or drag the image they already attached to Warp. If the image is no longer available on their system (clipboard overwritten, file deleted), they can still submit the issue with the agent's description of the image and no rendered screenshot — the issue is degraded but still useful.
13. When multiple images are attached, the drafted body contains one placeholder per image in the order the agent encountered them. The user can drop images in any order into any placeholder; the feature does not require per-image matching.
14. Attaching images does not change the issue's classification, title format, label (in-app-feedback), or target repository (warpdotdev/warp-external). It only changes the filing path and the body's artifacts section.
15. Duplicate-issue detection runs before filing regardless of whether images are attached. If a likely duplicate is found, no new issue is filed, no browser is opened, and the user is pointed at the existing issue — the image-specific flow is short-circuited.
16. No telemetry is captured from this feature. The feedback skill does not emit events when images are attached, when the browser is forced, when the user drops images in the browser, or when filing succeeds or fails. The feature's usage and outcomes are not measured by Warp, and neither the drafted issue nor the helper script's exit payload is exfiltrated to a telemetry backend. If future measurement is wanted, it is a separate, explicitly-scoped change and not an invariant of this spec.
17. The change is scoped to the feedback skill's filing flow. Other slash commands, other skills, and non-skill agent queries are unaffected by any skill-specific body or script changes. The underlying platform fix that lets skill invocations see user-attached images may benefit other skills as a side effect, but no other skill's behavior is redefined by this spec.
18. The user-visible outcome — an issue filed to warpdotdev/warp-external whose attached images render inline on the final issue — is stable across delivery paths. The issue's title format, body structure, classification, label (in-app-feedback), target repository, and duplicate-detection behavior do not change if the underlying delivery path changes in a later phase.
19. When a later delivery path removes the need for a manual drag-and-drop step, the agent's final response stops instructing the user to drop images, the drafted body stops containing placeholder lines, and image-bearing feedback completes in a single agent turn. The user is never asked to do work that a later delivery path has made unnecessary.
20. Selection between available delivery paths is not user-visible and does not require user configuration. When more than one path is available, the feature uses whichever completes filing with the fewest user actions. The user is not asked to pick a delivery path, and no Warp setting governs the choice.

Future delivery paths

The current drag-and-drop design is a deliberate phase-1 choice. It exists because there is no first-party GitHub API for attaching images to issues via gh, and Warp's existing server-side image storage (ambient-agent inputs, AI conversation artifacts) uses private GCS buckets with short-lived presigned URLs and task-scoped authorization — none of which are suitable for permanent embedding in public GitHub issues. Two alternative delivery paths are anticipated for later phases. Each preserves the invariants in Behavior and only changes how the image reaches GitHub.

First-party gh CLI attachment support

If GitHub later exposes a public API for attaching images during issue creation (for example, a gh issue create --attach <path> flag) or equivalent coverage in the GitHub MCP server, the feedback skill should use that path in place of the forced browser flow. User-visible effects under this path:

• No browser is opened for image-bearing feedback; filing completes in a single agent turn, matching today's text-only happy path.
• The drafted body contains no placeholder lines for images.
• The agent's final response reports the filed issue URL directly and does not instruct the user to paste or drop anything.
• The filed issue's attached images render the same way they do today in drag-and-drop-authored issues (standard user-attachments URLs or whatever shape the new API produces), so existing issues remain indistinguishable from new ones visually.

Warp-hosted persistent image service

If Warp later stands up a public, long-lived, unauthenticated image-hosting service distinct from today's ambient-agent and conversation-artifact buckets — one that returns stable URLs suitable for GitHub markdown embedding — the skill should upload each attached image through that service and embed ![alt](<persistent-url>) directly in the drafted issue body before filing. User-visible effects under this path:

• Filing completes in a single agent turn. No browser is opened, no drag-and-drop is required, and the drafted body contains rendered image references rather than placeholders.
• The filed issue shows rendered images on first load without any user action beyond running /feedback.
• If the hosted service later removes or expires an image, the filed issue will degrade to a broken image reference. The service must be designed with retention that matches or exceeds GitHub issue longevity to satisfy invariant 18 (stable user-visible outcome); any tighter retention is a regression relative to today's user-attachments lifetime and is out of scope for this feature.
• Users are not asked to opt in to their images being uploaded to a Warp-hosted service; the skill's privacy posture and user-visible consent flow for feedback submission remains the same as it is for text-only /feedback today. Any consent or review step added here applies uniformly, not only to image-bearing feedback.

Cross-path invariants

Across all current and future delivery paths, the feedback workflow — classification, clarifying questions, grounded references, duplicate detection, issue structure, and the in-app-feedback label on warpdotdev/warp-external — is unchanged. Only the final filing step and the corresponding final user-visible message differ. If any path cannot deliver the image to the filed issue for any reason, the failure is surfaced explicitly to the user rather than silently producing an image-less issue that claims success (invariant 10 continues to hold: when the browser cannot be opened, the fallback to gh issue create files the text-only issue and explicitly tells the user the images were not uploaded).