github-issue-planning

GitHub Issue Planning Skill

Use this skill when planning work tied to a GitHub issue and the plan should be persisted on that issue for team visibility.

Required Input

Do not proceed without one of:

• Full issue URL (https://github.com/{owner}/{repo}/issues/{number}), or
• Owner/repo plus issue number ({owner}/{repo}#{number})

If neither is available, ask for it first.

Persistence Contract (Managed Comment)

Persist the plan in one managed issue comment with a stable marker:

<!-- agentic:github-issue-plan -->

Rules:

• Exactly one managed comment per issue per planning thread.
• Update that managed comment in place on subsequent runs (idempotent).
• Keep the marker at the top of the comment body so it is discoverable.
• Use issue-comment-template.md as the body scaffold.

Decision Tree

1. MCP path (preferred):

• If GitHub MCP is available and configured, use MCP issue/comment tools to find existing comments containing <!-- agentic:github-issue-plan --> and update.
• Enforce deterministic managed-comment handling:
  • 0 matching comments: create one managed comment with marker + plan body.
  • 1 matching comment: update that exact managed comment.
  • More than 1 matching comment: stop and request manual cleanup before updating.

1. gh CLI fallback (primary fallback, not hard-block):

• If MCP is unavailable or misconfigured, continue using gh CLI.
• Check auth first:

gh auth status

• Create a managed comment:

gh issue comment {issue_number} --repo {owner}/{repo} --body-file /tmp/issue-plan.md

• Update existing managed comment (find exactly one comment id, then edit):

MATCHED_IDS=$(gh api repos/{owner}/{repo}/issues/{issue_number}/comments --paginate \
  --jq '.[] | select(.body | contains("<!-- agentic:github-issue-plan -->")) | .id')

MATCH_COUNT=$(printf "%s\n" "$MATCHED_IDS" | sed '/^$/d' | wc -l | tr -d ' ')
if [ "$MATCH_COUNT" -gt 1 ]; then
  echo "Multiple managed plan comments found; stop and ask for manual cleanup."
  exit 1
fi

COMMENT_ID=$(printf "%s\n" "$MATCHED_IDS" | sed '/^$/d' | head -n 1)

gh api repos/{owner}/{repo}/issues/comments/$COMMENT_ID \
  --method PATCH \
  --field body="$(cat /tmp/issue-plan.md)"