create-github-issues

name	create-github-issues
description	Collaboratively create GitHub issues from review findings
allowed-tools	Read, Bash, Glob, Grep
user-invocable	true

Create GitHub Issues

Collaborates with the user to create GitHub issues from confirmed katz issues and evaluation findings. The agent gathers the review data, proposes a format, and posts via gh after user approval.

Usage

/create-github-issues

Prerequisites

• The paper must be reviewed (confirmed issues and/or eval results exist).
• gh CLI must be authenticated and the repo must have a GitHub remote.
• The user should be ready to discuss what format they want.

Workflow

1. Gather review data

Load all the review findings:

katz issue list --state confirmed
katz eval results

For each confirmed issue, load full details with katz issue show <id> to get investigation notes, suggestions, and manuscript context.

Summarize what's available to the user:

• N confirmed issues across M themes
• N evaluations, X below A-
• Any suggestions recorded

2. Discuss format with the user

Ask the user what they want. Common options:

A. Single summary issue — One GitHub issue with all findings. Good for an initial review round. Structure:

• Pipeline summary (how many calls, candidates, confirmed)
• Confirmed issues grouped by theme, each as a checkbox
• Key eval findings (low grades with suggestions)
• Footer with tool info and commit hash

B. Themed issues — One GitHub issue per theme (e.g., "Identification & Design," "Statistical Interpretation," "Presentation"). Good when different team members own different areas.

C. Per-issue — One GitHub issue per confirmed katz issue. Good for tracking individual fixes. Each issue includes the manuscript quote, investigation notes, and suggested fix.

D. Custom — The user may want something else entirely. Follow their lead.

Present the options and let the user choose. Don't assume.

3. Compose the issue body

For each GitHub issue to create, compose a markdown body. Include:

• Manuscript quote: The relevant text from the paper, as a blockquote
• Problem: What's wrong, from the investigation notes
• Suggestion: The proposed fix, if one exists
• Location: Section name, line numbers
• Traceability: katz issue ID(s) for reference

For eval findings, include:

• Criterion: What was evaluated
• Grade: The letter grade
• Assessment: The narrative response
• Suggestion: How to improve

Use a HEREDOC with gh issue create:

gh issue create \
  --title "Review: descriptive title" \
  --body "$(cat <<'EOF'
## body content here

*Generated by [katz](https://github.com/expectedparrot/katz) on YYYY-MM-DD.*
EOF
)"

4. Review with the user before posting

Always show the user the composed issue body before creating it. Display the full markdown and ask for approval. The user may want to:

• Edit the title
• Remove or reword items
• Change the grouping
• Add context only they know

Do not post without explicit approval.

5. Create the issues

After approval, create via gh issue create. Report the URL(s) back to the user.

If creating multiple issues, create them sequentially and report each URL.

6. Labels and assignees

If the user wants labels or assignees, use:

gh issue create --title "..." --body "..." --label "review" --assignee "username"

Ask the user if they want these. Don't assume.

Guidelines

• The user drives the format. Your job is to gather data, propose options, and execute. Don't impose a structure.
• Show before posting. Always preview the full issue body before creating.
• Be concise. GitHub issues should be actionable, not exhaustive. Link back to the katz review report for full details.
• Group intelligently. If creating themed issues, group by the underlying concern, not by katz section. Five issues about the same bias claim should be one GitHub issue about the bias claim.
• Include enough context. The GitHub issue should be understandable without opening the katz report — include the manuscript quote and the suggestion.