/create-issue

name: create-issue
description: Create comprehensive GitHub issues with TDD plans, acceptance criteria, and agent instructions for autonomous PR lifecycle management

Create GitHub Issue Skill

Create comprehensive, well-structured GitHub issues with embedded agent instructions for autonomous PR lifecycle management.

Overview

This skill generates GitHub issues that are self-contained work packets. Each issue includes:

1. **Problem/Feature specification** with clear scope 2. **Technical specification** with types, schemas, and API design 3. **TDD Implementation Plan** with test-first cycles 4. **Acceptance Criteria** checklist 5. **Agent Instructions** for complete PR lifecycle (implementation → review → merge)

Usage

/create-issue

Interactive Flow

Step 1: Issue Type

Ask the user:

What type of issue is this?
1. Feature - New functionality
2. Bug - Something broken
3. Refactor - Improving existing code

Step 2: Brief Description

Brief description of the problem or feature? (1-2 sentences)

Step 3: Complexity Assessment

What's the estimated complexity?
1. Simple (< 1 day)
2. Medium (2-5 days)
3. Complex (> 1 week)

Step 4: Context Gathering

Any related files, services, or issues I should reference?
(Or say "explore codebase" and I'll investigate)

Step 5: Generate Issue

Based on inputs, generate the full issue using the appropriate template below.

---

Issue Templates

Feature Template

## Summary

[1-2 sentence description]

**Complexity**: [simple|medium|complex]
**Estimated Effort**: [X days]

---

## Problem

[What problem does this solve? Why is it needed?]

### Evidence

[Logs, metrics, user reports, or reasoning]

### Scope

- IN SCOPE: [what's included]
- OUT OF SCOPE: [what's explicitly NOT included]

---

## Architecture Decision

**Decision**: [What approach will be taken]
**Rationale**: [Why this approach, why NOT alternatives]

---

## Technical Specification

### Types/Interfaces

```typescript
// Key type definitions

### Zod Schemas (if applicable)

```typescript
// Validation schemas

API Endpoints (if applicable)

| Method | Path | Description | | ------ | ---- | ----------- |

Database Changes (if applicable)

[Schema changes, migrations needed]

---

TDD Implementation Plan

Cycle 1: [Happy Path]

it("should [expected behavior]", async () => {
  // Test code
});

Cycle 2: [Error Handling]

it("should handle [error case]", async () => {
  // Test code
});

Cycle 3: [Edge Cases]

Cycle 4: [Integration]

---

Error Handling

| Scenario | Behavior | Logging | | -------- | -------- | ------- |

---

Implementation Phases

Phase 1: [Core] (High Priority)

• [ ] Task 1
• [ ] Task 2

Phase 2: [Enhancement] (Medium Priority)

• [ ] Task 3

---

Files to Create/Modify

• **NEW**: `path/to/new/file.ts`
• `path/to/existing/file.ts` - [what changes]

---

Acceptance Criteria

• [ ] All TDD cycles implemented with passing tests
• [ ] Zero TypeScript errors (`pnpm typecheck`)
• [ ] Zero lint warnings (`pnpm lint`)
• [ ] All tests pass (`pnpm test --run`)
• [ ] **JSDoc documentation** added to all new/modified services
• [ ] **`docs/SERVICE_INVENTORY.md`** updated (if new/modified service)
• [ ] **Mock factories** added/updated (if new service)
• [ ] PR created and all CI checks pass
• [ ] **ALL code review comments addressed** (see Agent Instructions)
• [ ] All review threads resolved
• [ ] PR approved and merged

---

Agent Instructions

**CRITICAL**: Follow this protocol when implementing this issue. A PR is NOT complete until ALL steps are done.

Phase 0: Research (BEFORE writing any code)

**Read these files first to avoid reinventing the wheel:**

1. **Service Inventory** - Check for existing services that might already do what you need:

   # Read the service inventory
   cat docs/SERVICE_INVENTORY.md
   # Or search for specific functionality
   grep -i "embedding\|search\|cache" docs/SERVICE_INVENTORY.md

2. **Mock Factories** - Review existing mocks to reuse patterns:

   ls src/test-utils/factories/

3. **Similar Services** - Find services with similar patterns:

   # Find orchestrator patterns
   ls src/lib/services/*-orchestrator*.ts
   # Find persistence patterns
   ls src/lib/services/*-persistence*.ts

**Why this matters**: Reusing existing services and patterns saves time, maintains consistency, and prevents duplicate code.

Phase A: Implementation

1. Create feature branch from main: `git checkout -b feat/[short-name]` 2. Follow TDD cycles exactly as specified above 3. **Add JSDoc documentation** to all new/modified services 4. Run local validation: `pnpm lint && pnpm typecheck && pnpm test --run` 5. **Update service inventory** (if new service) 6. Create PR with comprehensive description using `/create-pr`

Phase B: Code Review Iteration

**Wait for code reviews before proceeding. Do NOT mark complete after pushing code.**

For EACH code review iteration:

1. **Fetch ALL comments** (including trivial, nitpicks, and out-of-scope):

   PR_NUMBER=XXX
   OWNER=$(gh repo view --json owner -q .owner.login)
   REPO=$(gh repo view --json name -q .name)
   gh api "repos/$OWNER/$REPO/pulls/$PR_NUMBER/comments" --paginate

2. **Address ALL comments by category**:

| Type | Action | | ---------------------- | ---------------------------------------------------- | | Critical/Major | Fix immediately | | Medium/Minor | Fix before merge | | **Trivial/Nitpick** | **Fix these too!** Do NOT skip | | **Out-of-scope** | **Investigate thoroughly** - often the BEST insights |

3. **For each comment**: