org-issues-tidy

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.