Workflow Improvement

# Automatic Issue Creation for Deferred Items

Reusable patterns for automatically creating GitHub issues when items are classified as deferred, backlog, out-of-scope, or suggestions during workflow execution.

## Philosophy

**Automatic by Default**: When items are explicitly classified as deferred/backlog during any workflow, they should be automatically logged to GitHub issues without requiring a separate flag or manual step. The user is notified of what was created.

## When to Use This Module

Include this module in any workflow that:
- Classifies items as "deferred", "backlog", "out-of-scope", or "suggestion"
- Identifies work that should be tracked but not addressed immediately
- Produces improvement recommendations with priority levels

## Integration Pattern

### Step 1: Collect Deferred Items

During workflow execution, collect deferred items in a structured format:

```bash
# Data structure for deferred items
DEFERRED_ITEMS=()

# Add items as they're identified
DEFERRED_ITEMS+=("type:suggestion|title:Improve error messages|source:PR #123|file:auth.py:45|description:Error messages could be more descriptive|labels:enhancement,plugin:sanctum")
DEFERRED_ITEMS+=("type:backlog|title:Add rate limiting|source:PR #123|file:routes.py|description:Consider adding rate limiting to API|labels:enhancement,low-priority")
```

### Step 2: Invoke Auto-Creation

At the end of the workflow (after all analysis is complete), invoke the auto-creation routine:

```markdown
## Auto-Create GitHub Issues

For each deferred item collected during this workflow:

1. **Check for duplicates** before creating
2. **Create the issue** with proper labels and context
3. **Report what was created** to the user
```

### Step 3: Duplicate Detection

Before creating any issue, check if a similar issue already exists:

```bash
# Search for existing issues with similar title
SEARCH_QUERY="$ITEM_TITLE in:title is:issue is:open"
EXISTING=$(gh issue list --search "$SEARCH_QUERY" --json number,title --jq '.[0].number // empty')

if [[ -n "$EXISTING" ]]; then
  echo "Skipping duplicate: Issue #$EXISTING already tracks '$ITEM_TITLE'"
  SKIPPED_ITEMS+=("$ITEM_TITLE (duplicate of #$EXISTING)")
else
  # Proceed with creation
fi
```

### Step 4: Issue Creation Template

```bash
create_deferred_issue() {
  local TYPE="$1"      # suggestion, backlog, deferred
  local TITLE="$2"     # Issue title
  local SOURCE="$3"    # Where it came from (PR #X, /update-plugins, etc.)
  local FILE="$4"      # file:line reference (optional)
  local DESC="$5"      # Description
  local LABELS="$6"    # Comma-separated labels

  # Determine prefix based on type
  case "$TYPE" in
    suggestion) PREFIX="[Suggestion]" ;;
    backlog) PREFIX="[Backlog]" ;;
    deferred|out-of-scope) PREFIX="[Deferred]" ;;
    improvement) PREFIX="[Improvement]" ;;
    *) PREFIX="" ;;
  esac

  # Create issue body
  BODY="## Context

Identified during $SOURCE as $TYPE item.

$(if [[ -n "$FILE" ]]; then echo "**Location:** \`$FILE\`"; fi)

## Description

$DESC

## Value

This improvement would enhance the codebase by addressing an identified opportunity.

## Acceptance Criteria

- [ ] Implementation complete
- [ ] Tests added/updated (if applicable)
- [ ] Documentation updated (if applicable)

---
*Auto-created by workflow execution*"

  # Create the issue
  ISSUE_URL=$(gh issue create \
    --title "$PREFIX $TITLE" \
    --body "$BODY" \
    --label "$LABELS" 2>&1)

  if [[ $? -eq 0 ]]; then
    echo "$ISSUE_URL"
  else
    echo "ERROR: $ISSUE_URL"
    return 1
  fi
}
```

### Step 5: Report Created Issues

After all issues are created, report to the user:

```markdown
### Issues Created (Automatic)

| Type | Title | Issue | Labels |
|------|-------|-------|--------|
| Suggestion | Improve error messages | [#115](url) | enhancement, plugin:sanctum |
| Backlog | Add rate limiting | [#116](url) | enhancement, low-priority |

**Skipped (duplicates):**
- "Fix validation" (duplicate of #42)
```

## Workflow-Speci