dev-skills

Appearance

GitHub Issue Editing ​

Edit GitHub issues and comments safely by downloading to temp files, modifying locally, then pushing changes back.

When to use ​

Use this pattern whenever you edit GitHub issues or comments via the API. Naive inline edits cause corruption because escaping mangles special characters, multiline content breaks, markdown formatting is lost, and Unicode characters disappear or transform. Round-tripping through local files avoids all of these problems.

The pattern ​

Always round-trip through local files:

  1. Download issue body or comment to a temp file
  2. Edit the temp file locally
  3. Push the temp file contents back to GitHub

Editing issue body ​

Download ​

sh
gh issue view {number} --json body --jq '.body' \
> .tmp/issue-{number}.md

Edit ​

Modify .tmp/issue-{number}.md with your changes.

Push ​

sh
gh issue edit {number} --body-file .tmp/issue-{number}.md

Editing comments ​

List Comments ​

sh
gh api repos/{owner}/{repo}/issues/{number}/comments \
  --jq '.[] | {id, body}'

Download Comment ​

sh
gh api repos/{owner}/{repo}/issues/comments/{comment_id} \
  --jq '.body' > .tmp/comment-{comment_id}.md

Edit ​

Modify .tmp/comment-{comment_id}.md with your changes.

Push Comment ​

sh
gh api repos/{owner}/{repo}/issues/comments/{comment_id} \
  -X PATCH --field body=@.tmp/comment-{comment_id}.md

Creating new comments ​

For new comments, write to a temp file first:

sh
echo "Your comment content" > .tmp/new-comment.md
gh issue comment {number} --body-file .tmp/new-comment.md

Hard rules — non-negotiable ​

Do NOT apply line length limits to GitHub markdown ​

Never wrap prose at 80 (or any fixed) characters in issue bodies, PR bodies, or comments. GitHub renders these fields as flowing markdown — the browser reflows text at whatever viewport width the reader uses. Hard line breaks inside a paragraph produce broken, jagged text in the rendered view, not readable prose.

Write each paragraph as a single unbroken line. Let the editor soft-wrap for readability while composing; never insert hard newlines mid-sentence.

The only places hard line breaks belong in GitHub markdown:

  • Blank lines between paragraphs
  • List items (each item on its own line)
  • Code blocks (already fenced)
  • Markdown table rows

This rule applies everywhere a GitHub field renders markdown: issue body, PR body, issue comments, PR review comments, and PR review summaries.

Integrate new information into the body; don't append it ​

When you learn something that changes an issue (a review, a spike, a decision in the comments), edit the body so it reads as if written once with everything known now. Don't tack an "Update:" section onto the end, and don't leave the correction only in a comment for every reader to reconcile. Comments are the conversation; the body is the current truth.

Once work has shipped against the issue (a plan executed, PRs merged), don't rewrite what people acted on. Put a superseded notice with a link to the new version at the very top of the old one, and make the new version self-contained.

The principle and its examples: Optimize for the Reader.

Trade-offs ​

  • NEVER pass content directly via --body flag with inline strings
  • ALWAYS use --body-file or --field body=@file for content
  • ALWAYS download before editing (don't reconstruct from memory)
  • Keep temp files in .tmp/ directory (gitignored)
  • Use descriptive filenames: issue-{number}.md, comment-{id}.md

Temp directory setup ​

Ensure .tmp/ exists and is gitignored:

sh
mkdir -p .tmp
echo ".tmp/" >> .gitignore  # if not already present