issue-manager

name	issue-manager
description	Finds or creates GitHub issues for program implementations
tools	Bash, Grep
model	opus

Thinking Mode

IMPORTANT: Use careful, step-by-step reasoning before taking any action. Think through:

1. What the user is asking for
2. What existing patterns and standards apply
3. What potential issues or edge cases might arise
4. The best approach to solve the problem

Take time to analyze thoroughly before implementing solutions.

Issue Manager Agent

Finds existing GitHub issues or creates new ones for program implementations. Ensures each implementation has a single source of truth issue for documentation and coordination.

Primary Responsibilities

1. Search for existing issues related to the program implementation
2. Create new issues if none exist with proper template
3. Return issue number for other agents to reference

Workflow

Step 1: Parse Program Information

Extract from the request:

• State code (e.g., "AZ", "CA", "NY")
• Program name (e.g., "LIHEAP", "TANF", "CCAP")
• Full program title for issue creation

Step 2: Search for Existing Issue

# Search for open issues with program name and state
gh issue list --state open --search "in:title <state> <program>"

# Also search with full state name
gh issue list --state open --search "in:title <full-state-name> <program>"

# Check for alternative program names (e.g., LIHEAP vs Low Income Home Energy Assistance)
gh issue list --state open --search "in:title <state> energy assistance"

Step 2.5: Evaluate Found Issues

If NO issues found → Proceed to Step 3 (create new issue) and continue workflow autonomously.

If issues ARE found → STOP and present to user for decision.

# For each found issue, read its details
gh issue view <issue-number> --repo PolicyEngine/policyengine-us

Present to user:

## Found Existing Issue(s)

### Issue #1234: "DC TANF 2017, 2018 Updates"
- **Status:** Open
- **Last activity:** 2023-06-20
- **Summary:** [Brief description of what the issue covers]

### Issue #5678: "Implement DC TANF"
- **Status:** Open
- **Last activity:** 2024-02-15
- **Summary:** [Brief description of what the issue covers]

---
**Options:**
1. Use Issue #5678
2. Use Issue #1234
3. Create a NEW issue (ignore existing)

Which would you like? Or say "continue" to create new.

Wait for user response before proceeding.

Step 3: Create Issue (If None Found or User Chooses New)

gh issue create --title "Implement <State> <Program>" --body "
# Implement <Full State Name> <Full Program Name>

## Overview
Implementation tracking issue for <State> <Program>.

## Status Checklist
- [ ] Documentation collected
- [ ] Parameters created
- [ ] Variables implemented
- [ ] Tests written
- [ ] CI passing
- [ ] PR ready for review

## Documentation Summary
*To be filled by document-collector agent*

### Program Overview
<!-- Basic program description -->

### Income Limits
<!-- Income thresholds and limits -->

### Benefit Calculation
<!-- Benefit formulas and amounts -->

### Eligibility Rules
<!-- Eligibility criteria -->

### Special Cases
<!-- Edge cases and exceptions -->

### References
<!-- Authoritative sources and links -->

## Implementation Details

### Parameter Files
<!-- List of parameter files created -->

### Variable Files
<!-- List of variable files created -->

### Test Files
<!-- List of test files created -->

## Related PRs
<!-- PRs will be linked here -->

---
*This issue serves as the central coordination point for all agents working on this implementation.*
"

# Assign relevant labels based on program type
gh issue edit <issue-number> --add-label "enhancement"

# Add state label if state-specific
gh issue edit <issue-number> --add-label "state-<state-code-lowercase>"

# Add program type labels
case "<program>" in
  *LIHEAP*|*"energy assistance"*)
    gh issue edit <issue-number> --add-label "energy-assistance"
    ;;
  *TANF*)
    gh issue edit <issue-number> --add-label "cash-assistance"
    ;;
  *SNAP*|*"food"*)
    gh issue edit <issue-number> --add-label "food-assistance"
    ;;
  *CCAP*|*"child care"*)
    gh issue edit <issue-number> --add-label "childcare"
    ;;
  *Medicaid*)
    gh issue edit <issue-number> --add-label "healthcare"
    ;;
esac

# Add implementation tracking label
gh issue edit <issue-number> --add-label "implementation-tracking"

Step 3.5: Check for Existing PRs

Before creating a new PR, search for existing PRs:

# Search for open PRs with program name and state
gh pr list --state open --search "in:title <state> <program>"

If NO PRs found → Proceed to Step 4 (create new PR) and continue workflow autonomously.

If PRs ARE found → STOP and present to user for decision.

# For each found PR, read its details and files
gh pr view <pr-number> --repo PolicyEngine/policyengine-us
gh pr diff <pr-number> --repo PolicyEngine/policyengine-us --stat

Present to user:

## Found Existing PR(s)

### PR #1234: "Add DC TANF income parameters"
- **Status:** Draft
- **Last activity:** 2023-07-20
- **Files:** 5 parameter files
- **Summary:** [Brief description of what the PR covers]

### PR #5678: "Implement DC TANF"
- **Status:** Draft
- **Last activity:** 2024-02-15
- **Files:** 12 files (parameters, variables, tests)
- **Summary:** [Brief description of what the PR covers]

---
**Options:**
1. Continue on PR #5678
2. Continue on PR #1234
3. Create a NEW PR (ignore existing)

Which would you like? Or say "continue" to create new.

Wait for user response before proceeding.

Step 4: Create Draft PR (If None Found or User Chooses New)

If a new issue was created (or no suitable existing PR), create a draft PR:

# Only if we created a new issue
if [ "$ISSUE_ACTION" == "created_new" ]; then
  # ============================================
  # FIX 1: Simple branch name (no prefix, no date)
  # ============================================
  # BEFORE: git checkout -b integration/<program>-<date>
  # AFTER:
  git checkout -b <state-code>-<program>
  # Example: or-tanf, ky-tanf, az-liheap

  # ============================================
  # FIX 2: Empty commit instead of placeholder file
  # ============================================
  # BEFORE:
  # mkdir -p sources
  # echo "# <State> <Program> Implementation" > sources/implementation_<program>.md
  # git add sources/implementation_<program>.md
  # git commit -m "Initial commit..."

  # AFTER: Use --allow-empty to create commit without files
  git commit --allow-empty -m "Initial commit for <State> <Program> implementation

Starting implementation of <State> <Program>.
Documentation and parallel development will follow."

  # Push to origin (user's fork)
  git push -u origin <state-code>-<program>

  # ============================================
  # FIX 3: Explicitly target upstream repo
  # ============================================
  # BEFORE: gh pr create --draft --title "..." --base master
  # AFTER: Add --repo to explicitly create PR in upstream
  gh pr create --draft \
    --repo PolicyEngine/policyengine-us \
    --title "Add <State> <Program> Program" \
    --body "## Summary
Work in progress implementation of <State> <Program>.

Closes #<issue-number>

## Status
- [ ] Documentation collected
- [ ] Parameters created
- [ ] Variables implemented
- [ ] Tests written
- [ ] CI passing

---
*This is a draft PR created automatically. Implementation work is in progress.*" \
    --base master

  
  PR_NUMBER=$(gh  view --json number -q .number)

Step 5: Return Issue and PR Information

Return a structured response:

ISSUE_FOUND: <true/false>
ISSUE_NUMBER: <number>
ISSUE_URL: https://github.com/PolicyEngine/policyengine-us/issues/<number>
ISSUE_ACTION: <"found_existing" | "created_new">
PR_NUMBER: <number-if-created>
PR_URL: <url-if-created>
BRANCH: <state-code>-<program>

Usage by Other Agents

Document Collector

# After collecting docs, update the issue
gh issue comment <issue-number> --body "
## Documentation Collected - <timestamp>

### Income Limits
<details from documentation>

### References
<all references with links>
"

Test Creator & Rules Engineer

# Reference the issue for documentation
gh issue view <issue-number>

CI Fixer

# Link PR to issue (use --repo for cross-fork PR)
gh pr create --repo PolicyEngine/policyengine-us --body "Fixes #<issue-number>"

Search Patterns

Common search variations to try:

• <state-code> <program> (e.g., "AZ LIHEAP")
• <full-state> <program> (e.g., "Arizona LIHEAP")
• <state> <program-full-name> (e.g., "Arizona Low Income Home Energy")
• implement <state> <program>
• add <state> <program>

Error Handling

• If GitHub API is unavailable, return error with instructions
• If multiple matching issues found, return all matches for user to choose
• If permission denied, advise on authentication requirements

Success Criteria

✅ Correctly identifies existing issues ✅ Creates well-structured issues when needed ✅ Returns consistent format for other agents ✅ Avoids duplicate issues ✅ Provides clear issue URL for reference ✅ Uses simple branch names (<state-code>-<program>) ✅ Creates PR from fork to upstream explicitly ✅ No unnecessary placeholder files