Tidy Issues Across an Org

Review open issues in an org's repos and add concise suggestions for clarity. Run from ~/code/{org}/ or pass the org name as an argument. Pass a specific repo name to limit scope (e.g. /org-issues-tidy epinowcast/baselinenowcast).

Accounts

Read bot_account, owner_account from the org's CLAUDE.md ## Automation config table.

Helper script

A pre-built script at ~/.claude/scripts/org-issues-scan.sh collects all open issues with metadata in one pass. Run it first to avoid spending tokens on individual gh calls.

~/.claude/scripts/org-issues-scan.sh <org-name> [repo-name] > /tmp/org-issues.json

If the script is missing or not executable, run /setup-scripts to regenerate it.

The script outputs a JSON array of issues with:

repo, gh_org, number, title, url, labels, createdAt, updatedAt
author_association (OWNER, MEMBER, COLLABORATOR, CONTRIBUTOR, NONE)
bot_commented (boolean — whether the bot account has already commented)
has_linked_pr (boolean)
is_assigned (boolean)

What to do

For each open issue where bot_commented is false, check if it would benefit from:

A clearer title
A minimal reproducible example
Breaking into smaller sub-issues
Labelling suggestions
A brief summary of the discussion so far (for long threads)

What NOT to do

Do not repeat work already done (skip issues where bot_commented is true)
Do not comment on issues that already have clear acceptance criteria
Do not add noise to active discussions
Do not suggest changes to issues opened in the last 24 hours (give the author time)
Keep comments under 100 words

Phase 1: Filter from script output

From the JSON, filter to issues where:

bot_commented is false
Issue is older than 24 hours
Score below 6 on the tidiness scale

Phase 2: Triage

Score each issue for "tidiness" (0-10):

Clear title (+2)
Reproducible example or clear steps (+2)
Labels assigned (+2)
Acceptance criteria stated (+2)
Recent activity within 7 days (+2)

Phase 3: Comment

For each issue needing attention, post a single concise comment via gh issue comment. Format:

A few suggestions to help move this forward:

- [specific, actionable suggestion]
- [specific, actionable suggestion]

This was posted by a bot. Please ping the repo owner for any questions.

Phase 4: Team mode

If more than 5 issues need comments, spawn a team. Each teammate handles a batch of issues for one repo.

Phase 5: Summary

Report:

Issues reviewed (count by repo)
Comments posted (with links)
Issues skipped (with reason)

Auto-Exit When Standalone

IMPORTANT: If this command is being run as a standalone request, automatically exit after completing all phases successfully.