Last updated: March 16, 2026

Writing good first issue descriptions is one of the most effective ways to grow an open source project. When issues are clear, well-structured, and approachable, new contributors feel confident jumping in. AI tools have become surprisingly good at helping maintainers craft these descriptions, and the right tool can transform a vague bug report into an inviting task that actually gets completed.

What Separates Good First Issues From Bad Ones

Before evaluating AI options, it helps to know what makes an issue description work. A first issue that attracts contributors includes several key elements:

• Context: Why does this issue exist? What user problem does it solve?

• Acceptance criteria: What does “done” look like? How will the fix be verified?

• Difficulty assessment: Is this genuinely appropriate for someone new to the codebase?

• Relevant code links: Direct references to files, functions, or modules that need changes

• Reproduction steps (for bugs): Precise steps so others can confirm the problem

AI tools that understand these elements can generate descriptions that hit all the right points while matching your project’s specific tone and conventions.

Comparing AI Tools for Issue Writing

Several AI assistants can help with this task, but they vary significantly in how well they understand open source workflows and how much context they can absorb about your project.

Claude and ChatGPT

Both Claude and ChatGPT handle issue writing well when given proper context. You can paste in existing issues, your CONTRIBUTING.md file, and code snippets, then ask for improvements. The main difference is in how they handle iteration—Claude tends to preserve your voice more consistently through multiple revision rounds, while ChatGPT sometimes defaults to more generic language.

A practical approach works well with either tool:

Write a first-time contributor issue for this GitHub issue:

Project: [project name]
Type: Bug fix / Feature / Documentation
Issue summary: [your brief notes]
Difficulty: beginner / intermediate

Context from our CONTRIBUTING.md:
[paste relevant section]

Code location:
[paste relevant code or file paths]

Please write a clear issue description that:
1. Explains why this matters
2. Includes acceptance criteria
3. Mentions the relevant files
4. Is welcoming to newcomers

This prompt structure gives the AI exactly what it needs to produce a useful result.

GitHub Copilot

Copilot integrates directly into your GitHub workflow and can suggest issue descriptions as you type. Its strength is convenience—you never leave the interface. However, it works best when you already have a solid outline. Copilot struggles more with generating complete descriptions from scratch without significant input.

For teams already using Copilot for code, the issue description suggestions are a nice bonus, but they rarely match what you’d get from a dedicated conversation with Claude or ChatGPT.

Cursor and Windsurf

These AI-powered editors offer more context-aware suggestions because they understand your entire codebase. When writing issues, they can reference actual functions, classes, and recent changes. This contextual awareness produces more specific and useful descriptions.

Cursor’s advantage is its ability to pull in relevant code automatically when you describe what an issue should cover. You can say “write an issue for the login function that’s missing error handling” and it will find the relevant code and incorporate it.

Writing Issue Descriptions That Work

Regardless of which AI tool you choose, the output quality depends heavily on how you frame the request. Here are practical patterns that produce better results.

Include Project Context

Always tell the AI about your project’s domain and terminology. A description written for a Kubernetes operator needs different language than one for a JavaScript UI library. Provide:

• What the project does in one sentence

• Key terminology your project uses

• Links to similar resolved issues for style reference

Specify the Contributor Level

Be explicit about whether this is truly a beginner-friendly issue. New contributors need issues that don’t require deep domain knowledge. A good prompt:

This should be approachable for someone's first contribution. They should be able to understand it without reading more than 2-3 other files.

Request Specific Sections

Instead of asking for “a good issue description,” request exactly the sections you want:

Write an issue with these sections:
1. Problem (what user-facing behavior needs fixing)
2. Expected vs actual behavior
3. Environment details
4. Acceptance criteria (3-5 specific checkboxes)
5. Files likely involved

This produces more consistent, scannable issues.

Example: Before and After

Here’s how AI transforms a poor issue description into something that attracts contributors:

Before (poor):

The login is broken. It doesn't work. Need to fix it.

After (AI-improved):

## Problem
Users report that login fails silently when entering valid credentials. The app displays no error message and simply returns to the login page.

## Expected Behavior
After entering correct username and password, users should see the dashboard within 3 seconds.

## Actual Behavior
The page refreshes and returns to login with no feedback. No error appears in browser console.

## Environment
- Browser: Chrome 120+
- OS: macOS 14, Windows 11
- App version: 2.3.1

## Acceptance Criteria
- [ ] Login with valid credentials redirects to dashboard
- [ ] Login with invalid credentials shows specific error message
- [ ] Error message is accessible (screen reader compatible)
- [ ] Fix works with both email/password and OAuth providers

## Relevant Code
- `auth/login.js` - authentication handler
- `components/LoginForm.vue` - form component
- `api/auth.ts` - API client

## Difficulty
This is a good first issue. It involves one API endpoint and one form component. No database changes required.

The AI version includes everything a new contributor needs to get started immediately.

Tips for Better AI-Generated Issues

Getting the best results requires some refinement:

1. Iterate on drafts: Generate a first version, then ask for improvements focused on clarity or concision.

2. Add your own context: AI doesn’t know project-specific quirks. Add notes about common pitfalls or related issues to watch for.

3. Check technical accuracy: AI sometimes suggests wrong file paths or outdated API references. Always verify the code it mentions exists.

4. Match your project’s voice: Some projects are casual, others formal. Tell the AI the appropriate tone.

5. Keep issues focused: If an issue touches multiple areas, consider splitting it. AI can help identify natural break points.

Automating Good First Issue Creation

Create a GitHub Actions workflow that drafts good-first-issues automatically:

name: Draft Good First Issue
on:
  issues:
    types: [labeled, opened]

jobs:
  draft-issue:
    if: contains(github.event.issue.labels.*.name, 'good-first-issue')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate Issue Improvement
        env:
          CLAUDE_API_KEY: ${{ secrets.CLAUDE_API_KEY }}
        run: |
          python3 << 'EOF'
          import requests
          import os
          import json

          issue_body = os.getenv('ISSUE_BODY')
          issue_title = os.getenv('ISSUE_TITLE')

          # Prepare context
          with open('.github/CONTRIBUTING.md', 'r') as f:
            contributing = f.read()

          # Request improvement from Claude
          response = requests.post(
            'https://api.anthropic.com/v1/messages',
            headers={
              'x-api-key': os.getenv('CLAUDE_API_KEY'),
              'content-type': 'application/json'
            },
            json={
              'model': 'claude-opus-4-6',
              'max_tokens': 1500,
              'system': '''You are an expert at improving GitHub issues for beginners.
              Rewrite this issue to be more beginner-friendly:
              - Add clear acceptance criteria
              - Include relevant file locations
              - Estimate difficulty level
              - Explain why this matters''',
              'messages': [{
                'role': 'user',
                'content': f'''Issue Title: {issue_title}
                Issue Body: {issue_body}
                Our Contributing Guide: {contributing}'''
              }]
            }
          )

          improved = response.json()['content'][0]['text']
          with open('improved_issue.md', 'w') as f:
            f.write(improved)
          EOF

      - name: Post as Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const improved = fs.readFileSync('improved_issue.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '## Suggested Improvement\n\n' + improved
            });

This automation reviews every labeled issue and suggests enhancements as a comment.

Measuring Issue Quality Impact

Track how well-written issues correlate with contributor engagement:

Issue Template for AI Prompting

Create a standard template that AI tools understand:

type: bug|feature|documentation
difficulty: beginner|intermediate|advanced
estimated_time: 30min|1hour|2hours|4hours+
---

## Problem
[What's broken or missing?]

## Table of Contents

- [Problem](#problem)
- [Expected vs Actual](#expected-vs-actual)
- [Reproduction Steps](#reproduction-steps)
- [Acceptance Criteria](#acceptance-criteria)
- [Resources](#resources)
- [For Beginners](#for-beginners)
- [CLI for Batch Issue Improvement](#cli-for-batch-issue-improvement)
- [Issue Writing Checklist for AI](#issue-writing-checklist-for-ai)

## Expected vs Actual
[How should it work? How does it currently work?]

## Reproduction Steps
1. [Step 1]
2. [Step 2]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Resources
- [Link to relevant code]
- [Link to documentation]

## For Beginners
[This explains the simpler version of the problem...]

When using this template with AI tools, response quality improves significantly because the structure is explicit.

CLI for Batch Issue Improvement

Process multiple existing issues efficiently:

#!/bin/bash
# improve-issues.sh - Batch process existing issues

REPO=$1
LABEL=${2:-"good-first-issue"}

# Get all issues with label
gh issue list \
 --repo "$REPO" \
 --label "$LABEL" \
 --json number,title,body \
 --template '{{range .}}{{.number}}|{{.title}}|{{.body}}{{"\n"}}{{end}}' | \
while IFS='|' read issue_num title body; do
 echo "Processing issue #$issue_num..."

 # Call AI to improve
 claude_response=$(curl -s -X POST https://api.anthropic.com/v1/messages \
 -H "x-api-key: $CLAUDE_API_KEY" \
 -H "content-type: application/json" \
 -d '{
 "model": "claude-opus-4-6",
 "max_tokens": 1000,
 "system": "Improve this GitHub issue for beginners",
 "messages": [{"role": "user", "content": "Title: '"$title"'\n\nBody: '"$body"'"}]
 }' | jq -r '.content[0].text')

 # Save improvements
 echo "=== Issue #$issue_num ===" >> improvements.txt
 echo "$claude_response" >> improvements.txt
 echo "" >> improvements.txt
done

echo "Improvements saved to improvements.txt"
echo "Review and apply manually to each issue"

Run this to improve all issues in a batch, then review before applying.

Issue Writing Checklist for AI

Before asking AI to improve an issue, verify it contains:

• Clear problem statement (1-2 sentences)
• Why this matters (user impact)
• Reproduction steps or example
• Expected vs actual behavior
• File or code location references
• Acceptance criteria (3-5 checkboxes)
• Difficulty estimation
• Time estimate (30min to 4 hours)
• Links to related issues
• Technology stack specifics

The more complete your input, the better the AI-improved output.

Frequently Asked Questions

What if the fix described here does not work?

If the primary solution does not resolve your issue, check whether you are running the latest version of the software involved. Clear any caches, restart the application, and try again. If it still fails, search for the exact error message in the tool’s GitHub Issues or support forum.

Could this problem be caused by a recent update?

Yes, updates frequently introduce new bugs or change behavior. Check the tool’s release notes and changelog for recent changes. If the issue started right after an update, consider rolling back to the previous version while waiting for a patch.

How can I prevent this issue from happening again?

Pin your dependency versions to avoid unexpected breaking changes. Set up monitoring or alerts that catch errors early. Keep a troubleshooting log so you can quickly reference solutions when similar problems recur.

Is this a known bug or specific to my setup?

Check the tool’s GitHub Issues page or community forum to see if others report the same problem. If you find matching reports, you will often find workarounds in the comments. If no one else reports it, your local environment configuration is likely the cause.

Should I reinstall the tool to fix this?

A clean reinstall sometimes resolves persistent issues caused by corrupted caches or configuration files. Before reinstalling, back up your settings and project files. Try clearing the cache first, since that fixes the majority of cases without a full reinstall.

Related Articles

• Best AI for Writing Good First Issue Descriptions That
• Best AI Assistant for Writing Open Source Roadmap Documents
• AI Tools for Writing App Store Descriptions 2026
• AI Tools for Analyzing Which Open Source Issues Would Benefi
• AI Tools for Analyzing Issue Comment Sentiment to Identify Built by theluckystrike — More at zovo.one