Github Issues From Spec

1. Specification source - File path, pasted text, or plan file
2. Repository - GitHub repo (e.g., LexiconIndonesia/backend)
3. Project name - GitHub project to add issues to (e.g., Lexicon)
4. System field - Value for the System field
5. Status field - Initial status for issues (default: Backlog)
6. Priority field - Priority level for issues (default: P1)
7. Size field - Estimated size of the issue (default: S)

Available Status Values:

Available Priority Values:

Available Size Values:

Available System Values:

Or paste your specification directly.

Read and analyze the specification to identify:

• Feature components
• Dependencies between features
• Acceptance criteria
• Technical requirements

Step 2: Chunk into Issues

Break down the specification into issues following these principles:

Issue Sizing:

• Each issue = 1-4 hours of work
• Single, testable commit
• Clear acceptance criteria
• No dependencies within the same issue

Issue Types:

Step 3: Structure Each Issue

Use this template for each issue:

## Description

Brief description of what needs to be done.

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Technical Notes

- Implementation hints
- Files to modify
- Dependencies

## Testing

- [ ] Unit tests added/updated
- [ ] Integration test (if applicable)
- [ ] Manual verification steps

Step 4: Determine Labels

Assign labels based on issue content:

Size labels:

• size: XS - Trivial change
• size: S - Small, focused change
• size: M - Medium, multiple files
• size: L - Large, should consider breaking down

Priority labels:

• priority: High - Blocking or critical path
• priority: Medium - Important but not blocking
• priority: Low - Nice to have

Type labels:

• enhancement - New feature
• bug - Bug fix
• documentation - Docs only
• refactor - Code improvement

Step 5: Create Issues via gh CLI

For each issue, create using gh CLI:

gh issue create \
  --repo "Owner/Repo" \
  --title "Issue title" \
  --body "$(cat <<'EOF'
## Description

Description here

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

## Technical Notes

Notes here
EOF
)" \
  --label "size: S" \
  --label "priority: High" \
  --label "enhancement"

Step 6: Add to Project

Add each created issue to the GitHub project:

# Get project ID
gh project list --owner "Owner" --format json | jq '.projects[] | select(.title=="ProjectName") | .number'

# Add issue to project
gh project item-add PROJECT_NUMBER --owner "Owner" --url "ISSUE_URL"

# Set project fields (if needed)
gh project item-edit --project-id PROJECT_ID --id ITEM_ID --field-id FIELD_ID --text "Value"

Step 7: Set Project Fields

Update project-specific fields:

# Get field IDs
gh project field-list PROJECT_NUMBER --owner "Owner" --format json

# Set System field (text field)
gh api graphql -f query='
  mutation {
    updateProjectV2ItemFieldValue(input: {
      projectId: "PROJECT_ID"
      itemId: "ITEM_ID"
      fieldId: "SYSTEM_FIELD_ID"
      value: { text: "Backend" }
    }) {
      projectV2Item { id }
    }
  }
'

# Set Status field (single select field)
gh api graphql -f query='
  mutation {
    updateProjectV2ItemFieldValue(input: {
      projectId: "PROJECT_ID"
      itemId: "ITEM_ID"
      fieldId: "STATUS_FIELD_ID"
      value: { singleSelectOptionId: "OPTION_ID" }
    }) {
      projectV2Item { id }
    }
  }
'

Single Select Option IDs: Query the project to get option IDs for Status, Priority, and Size fields.

API Endpoint Issue

## Description

Implement `{METHOD} /api/v1/{path}` endpoint.

## Acceptance Criteria

- [ ] OpenAPI spec updated
- [ ] Handler implemented
- [ ] SQLC query added (if needed)
- [ ] Response matches spec
- [ ] Tests pass

## Technical Notes

- Files: `api/openapi.yaml`, `internal/api/handlers.go`
- Cache key: `{cache_key}` (if applicable)

Database Migration Issue

## Description

Add migration for {description}.

## Acceptance Criteria

- [ ] Migration file created
- [ ] UP migration works
- [ ] DOWN migration works
- [ ] SQLC queries updated

## Technical Notes

- Migration name: `{name}`
- Affected tables: {tables}

Filter/Search Enhancement Issue

## Description

Add {filter_name} filter to {endpoint} endpoint.

## Acceptance Criteria

- [ ] Filter parameter added to OpenAPI spec
- [ ] SQLC query updated with filter logic
- [ ] Handler processes filter correctly
- [ ] Empty filter returns all results
- [ ] Filter values validated

## Technical Notes

- Use `ANY(array)` pattern for multi-value filters
- Add to existing filter endpoint if applicable

For creating multiple issues from a markdown file:

#!/bin/bash
# create_issues.sh

REPO="Owner/Repo"
PROJECT="ProjectName"
SYSTEM="Backend"
STATUS="Backlog"    # Options: Backlog, Ready, In progress, In review, Done
PRIORITY="P1"       # Options: P0, P1, P2, P3
SIZE="S"            # Options: XS, S, M, L, XL

# Find project number
PROJECT_NUM=$(gh project list --owner "Owner" --format json | jq -r '.projects[] | select(.title=="'"$PROJECT"'") | .number')

echo "Creating issues for $REPO, Project #$PROJECT_NUM"

# Parse Issues.md and create each issue
# (Implementation depends on file format)

# Example: Create single issue
ISSUE_URL=$(gh issue create \
  --repo "$REPO" \
  --title "Issue title" \
  --body "Issue body" \
  --label "size: S,priority: High" \
  2>&1 | grep -o 'https://.*')

echo "Created: $ISSUE_URL"

# Add to project
gh project item-add "$PROJECT_NUM" --owner "Owner" --url "$ISSUE_URL"

Before creating issues:

• Labels exist in repository (create if not)
• Project exists and is accessible
• System field exists in project
• Status field exists in project (Backlog, Ready, In progress, In review, Done)
• Priority field exists in project (P0, P1, P2, P3)
• Size field exists in project (XS, S, M, L, XL)
• Issues are properly sized (not too large)
• Dependencies are documented
• No duplicate issues exist

After creating issues, provide summary:

# Issue Creation Summary

**Repository:** Owner/Repo
**Project:** ProjectName
**Total Issues Created:** X

| # | Title | Size | Priority | URL |
|---|-------|------|----------|-----|
| 1 | Issue title | S | High | https://... |
| 2 | Issue title | M | Medium | https://... |

## Next Steps

1. Review created issues
2. Adjust priorities if needed
3. Assign to team members
4. Add to sprint/milestone

Converted and distributed by TomeVault — claim your Tome and manage your conversions.