Github Visual Planning Issues

GitHub Visual Planning Issues

Class of task

Use this for review-friendly GitHub planning issues where the deliverable is a structured issue body with visual thumbnails and links, especially when replacing or superseding a stale issue.

Workflow

1. Inspect the prior issue first

   • Use gh issue view <number> --repo <owner/repo> --json number,title,state,url,body,labels,comments.
   • Identify what is stale, seasonal, duplicated, or still useful.
   • If the issue is travel/season/date-sensitive, explicitly separate current-realistic expectations from seasonal/historical expectations (e.g., tulips, fall color, clear beach water, waterfall flow).

2. Search for duplicates / related issues

   • Use gh issue list --repo <owner/repo> --state all --search "key terms" --json number,title,state,url.
   • Reuse the old issue if it substantially covers the new request; otherwise create a replacement and cross-link.

3. Collect source-backed visuals and official links

   • Prefer official destination/vendor pages, repository assets, or credible pages that expose direct image URLs.
   • For travel/destination planning, capture both: (a) the official destination planning link, and (b) a direct preview image URL suitable for GitHub markdown.
   • Browser flow: navigate to source page → browser_get_images → choose images with meaningful alt, width/height, and stable URLs.
   • If direct images are hard to retrieve, inspect OpenGraph/Twitter metadata (og:image, og:title, description) with a small script and cite the source URL.
   • Do not download/rehost images unless explicitly needed; direct source URLs are enough for GitHub markdown review boards.

4. Draft a visual review board

   • Use compact tables with HTML thumbnails for predictable sizing:

| Option | Preview | Notes |
|---|---|---|
| Candidate A | <img src="https://example.com/a.jpg" width="260" alt="Candidate A exterior"> | Why this option matters |

• Include source links near the visual table.
• Use descriptive alt text for review and accessibility.
• For travel/scenic issues, add a realistic season/timing board so photos do not create false expectations:
  • what scenery is probable in spring/summer/fall/winter;
  • what depends on live conditions (bloom reports, rainfall/waterfall flow, beach surf/water clarity, wildfire/haze, crowds, mosquitoes, closures);
  • which images are representative marketing/source photos versus exact same-week conditions.
• If the user asks for seasonal photos, make the unit explicit before/while posting: one photo per season per issue means 4 total previews (spring/summer/fall/winter), while four photos per season means 16 previews per issue. When the request is ambiguous, prefer a compact 4-total four-season board first and state the interpretation; offer expansion to 16 if they want deeper review.
• For broad trip portfolios, apply the same four-season preview standard consistently to legacy/general issues, parent route issues, and dedicated child destination issues so no review link lacks visual seasonal context.
• Add an explicit verification rule: before booking, check recent visitor photos from the last 30–90 days, official alerts/closures, weather, and the exact lodging/listing photos.

5. Use body files, not inline bodies

   • Write long markdown to /tmp/<issue-slug>.md.
   • Create with gh issue create --body-file /tmp/<issue-slug>.md.
   • This avoids shell interpretation of markdown, image tags, pipes, parentheses, and backticks.

6. Avoid title parsing pitfalls

   • If a title contains & or other shell-significant characters, replace with words like and or quote carefully.
   • Some terminal wrappers may reject a literal & in a foreground command even if shell-quoted.

7. Create and verify

   • Create: gh issue create --repo OWNER/REPO --title 'Title' --body-file /tmp/body.md --label documentation.
   • Verify: gh issue view <new-number> --repo OWNER/REPO --json number,title,state,url,labels,body.
   • Check that image HTML is present and not mangled.

8. For portfolios, create a navigable issue tree

   • If a user asks for multiple destinations/options, create one parent/portfolio issue per major route/state/category and one dedicated child issue per destination when individual review links are useful.
   • Back-link every child to its parent and post a parent comment listing all child GitHub issue links so the parent becomes the navigation hub.
   • Keep each child issue focused on one destination/route: official planning link, why consider it, realistic preview photo, best timing, caveats, and a short decision checklist.
   • For alternate travel/state portfolios, include a quick comparison/ranking dimension such as scenic-probability, drive reality from the origin, weather/season risk, and lodging feasibility.
   • When the user needs family/stakeholder review order, post a master ranked index plus a small ranking comment on each child issue. Make links visibly clickable, not just raw URLs buried in text:
     • master index format: | Rank | Destination | GH link | with rows like [Open issue #NN](https://github.com/OWNER/REPO/issues/NN);
     • per-issue ranking comment format: | Field | Value | with Overall rank, Destination, GH link, and Review tier;
     • include plain-text fallback URLs below the table, because some chat/browser contexts hide or de-emphasize Markdown links;
     • after posting, verify mechanically that every target comment contains the visible-link heading, its own issue URL, and the master ranking URL.
   • If an already-posted index/comment has hidden or hard-to-see links, patch the existing GitHub comment with gh api -X PATCH repos/OWNER/REPO/issues/comments/COMMENT_ID --input body.json rather than adding duplicate correction comments.
   • Keep titles class-readable and shell-safe: Travel Plan: <Origin> to <Destination or Region> scenic trip or Destination: <Name>, <State>.
   • After bulk creation/commenting, verify coverage mechanically, e.g. loop through issue numbers and test whether body/comments contain <img src= or markdown images, then inspect a sample of rendered issue comments.

9. Comment on the superseded or parent issue

   • If the old issue is stale/seasonal, add a short comment with the new issue link and why it supersedes the old one.
   • If the new issues are alternatives to an existing route/portfolio, add a short index/ranking comment to the existing issue with all new links.
   • Leave old issues open unless the user asked to close them or closeout policy is clear.

Minimal checklist

• Prior issue inspected.
• Duplicate/related issue search completed.
• Labels inspected/reused.
• Visuals have direct URLs and source links.
• Seasonal/current-condition caveats added when visuals are time-sensitive.
• Visuals have direct URLs and source links.
• Official planning links are included for each option/destination.
• Seasonal/date-sensitive expectations are stated when timing affects enjoyment.
• If seasonal photos are requested, the issue/comment clearly states whether it is 4 total previews (one per season) or 16 previews (four per season).
• For trip portfolios, every legacy/general, parent, and child destination issue has comparable seasonal visual context.
• Body written via --body-file.
• Title avoids problematic shell metacharacters.
• New issue verified after creation.
• For parent/child portfolios, parent issue has a link-index comment to all child issues.
• For alternate travel/state portfolios, each child has scenic-probability, drive-reality, timing/weather caveats, and lodging-feasibility notes.
• Superseded or parent issue commented with replacement/alternative links.