gh-issue

GitHub Issue Creation

Create clear, actionable GitHub issues for bugs, features, and improvements. Issues are primarily consumed by LLMs, so optimize for agent readability and actionability.

When to Create an Issue

• Bugs discovered during development or testing
• Feature requests from product/design
• Technical debt or refactoring needs
• Schema changes requiring migrations
• Missing error handling, telemetry, or validation
• Architectural improvements

Required: Always Use the llm Label

Every issue MUST include the llm label. This ensures the issue appears in LLM-facing issue feeds and boards.

gh issue create --title "..." --label llm --body "..."

Issue Structure

Structure issues to help LLMs understand the problem and intended outcome without prescribing implementation details.

Template

## Problem

Clear, concise description of what is wrong or missing. One paragraph maximum.

## Impact

- Bullet points describing why this matters
- What breaks or what capability is missing
- User-facing consequences (if any)

## Proposed Solution (Optional)

High-level approach to fixing the problem. Do NOT include:
- Specific file paths
- Exact code snippets or function names
- Step-by-step implementation instructions
- Migration SQL (unless the issue IS the migration)

DO include:
- Which components/systems are involved
- Expected behavior after the fix
- Any constraints or requirements

## Acceptance Criteria

- [ ] Observable outcome 1
- [ ] Observable outcome 2
- [ ] Tests pass / typechecks pass

Example: Good Issue

## Problem

The outbox_events table has an aggregate_id column but no aggregate_type, 
making it impossible to query events by entity type without parsing payloads.

## Impact

- Cannot build audit trails by entity type (e.g., "all organization events")
- Difficult to implement event replay for specific domains
- No way to validate event sources at the database level

## Proposed Solution

Add an aggregate_type column to outbox_events. Events should specify their 
entity type ("organization", "user", "project"). System-level events without 
a clear aggregate should use aggregate_type: "system" with a generated ID.

## Acceptance Criteria

- [ ] Migration adds aggregate_type column with index
- [ ] OutboxEventWriterShape updated to accept aggregateType
- [ ] All existing outboxWriter.write() calls updated
- [ ] Can query events by aggregate_type

Example: Bad Issue (Too Prescriptive)

## Problem

Missing column in outbox_events table.

## Solution

1. Add `aggregate_type VARCHAR(64)` to packages/platform/db-postgres/src/schema/outbox-events.ts
2. In packages/domain/events/src/outbox-event-writer.ts, change OutboxEventWriterShape:
   export interface OutboxEventWriterShape {
     write(event: {
       aggregateType: string  // ADD THIS
       ...
     })
   }
3. Update apps/web/src/domains/organizations/organizations.functions.ts line 55:
   await outboxWriter.write({
     aggregateType: "organization",  // ADD THIS
     ...
   })

Why this is bad: Prescribes exact implementation. Future LLM may find better approaches or hit blockers not anticipated by issue author.

Creating Issues via CLI

# Simple inline body
gh issue create --title "Fix type inference in eval scorer" --label llm --body "Problem: Eval scorer returns any type. Impact: No type safety on scores. Solution: Add generic type parameter to score() function."

# From file
gh issue create --title "Add rate limiting to API" --label llm --body "$(cat <<'EOF'
## Problem

API endpoints lack rate limiting, vulnerable to abuse.

## Impact

- Potential for DOS attacks
- No protection against brute force
- Unpredictable resource usage

## Proposed Solution

Implement rate limiting middleware on API routes. Consider per-user and global limits.

## Acceptance Criteria

- [ ] Rate limiting applied to all public API endpoints
- [ ] Returns 429 status when limit exceeded
- [ ] Limits configurable via environment
EOF
)"

Labels Beyond llm

Add additional labels when applicable:

• bug - Something is broken
• enhancement - New feature or improvement
• tech-debt - Refactoring or cleanup
• database - Schema or migration changes
• security - Security-related fix
• docs - Documentation only

Always pair these with llm.

What to Avoid

❌ Implementation details (specific files, line numbers, exact code) ❌ Step-by-step instructions ❌ Guessing at root causes without evidence ❌ Multiple unrelated problems in one issue ❌ Vague titles like "Fix stuff" or "Improve code"

What to Include

✅ Clear problem statement ✅ Impact/rationale for fixing ✅ High-level solution approach (optional) ✅ Acceptance criteria as checkboxes ✅ The llm label (always)

Handling Uncertainty

If the problem is clear but the solution is unknown:

## Problem

Intermittent timeouts in background job processing during high load.

## Impact

- Jobs fail silently after 30s
- Data processing delays during peak hours
- No visibility into which jobs are affected

## Proposed Solution

Unknown. Investigation needed to determine if this is:
- Queue worker configuration issue
- Database connection pool exhaustion
- External API timeout handling

## Investigation Notes

- Timeout occurs in @app/workers job handlers
- Correlates with span ingestion volume spikes
- Check worker logs around 2024-01-15 14:00 UTC

## Acceptance Criteria

- [ ] Root cause identified
- [ ] Fix implemented and tested
- [ ] Monitoring added to detect recurrence