---

name: first-issue-designer description: "Use when asked to create good first issues, prepare a repo for new contributors, turn a roadmap into starter tasks, or write issues that newcomers can actually finish. Produces 8 to 12 good first issues from a codebase and roadmap, each with context, acceptance criteria, files to touch and an effort estimate, plus the labels and a short pinned welcome note. For the CONTRIBUTING guide itself, use contributor-guide." version: 1.0.0

First Issue Designer

A good first issue is a small, real task that a stranger can finish in one sitting without asking the maintainer anything. Most "good first issue" labels sit on tasks that are vague, secretly large, or blocked on a decision only the maintainer can make. This skill reads the codebase and roadmap and writes 8 to 12 issues that newcomers can pick up and finish.

Required Inputs

Ask for these if not provided:

• The repo: structure, main language, how to run tests
• The roadmap or backlog: what the maintainer wants done next
• Things the maintainer does not want touched: core modules, areas mid-refactor
• Review capacity: how many PRs a week the maintainer can review
• Existing labels and any CONTRIBUTING guide

Output Structure

1. Candidate scan

A table of possible tasks found in the roadmap, TODO comments, failing or missing tests, docs gaps and small bugs: | Candidate | Source | Size guess | Keep or drop | Reason |

Drop anything that needs a design decision, touches more than three files, or depends on another open task.

2. The issues (8 to 12)

Each issue in this exact format, ready to paste:

**Title:** [Verb] [object] in [place]   (e.g. "Add a --json flag to the export command")

**Context**
[Two or three sentences: why this matters to users and where it fits.]

**What to do**
1. [Step]
2. [Step]

**Acceptance criteria**
- [ ] [Observable result]
- [ ] [Test added or updated: name the test file]
- [ ] [Docs updated, if user-facing]

**Files to touch**
- `path/to/file` (what changes there)

**Effort:** [about 1 hour | about 2 hours | half a day]
**Skills needed:** [e.g. basic TypeScript, no framework knowledge]
**Labels:** good first issue, [area label]

3. Mix check

A table showing the spread across types (docs, tests, small feature, bug, tooling) and effort. Aim for at least three issues under two hours and no more than two at half a day.

4. Pinned welcome note

A short note (under 120 words) for a pinned issue or discussion: how to claim an issue, how long a claim lasts, where to ask, and how quickly PRs are reviewed, matching the stated review capacity.

Quality Checks

• Between 8 and 12 issues, each in the exact format above
• Every issue names the files to touch and at least one test or doc to update
• Every acceptance criterion is observable (a command, output or page someone can check)
• No issue requires a decision the maintainer has not made
• No issue touches more than three files or depends on another open issue
• At least three issues are estimated at two hours or less
• The welcome note's review promise matches the stated review capacity

Anti-Patterns

• "Improve the docs". Too vague to finish. Name the page and the missing section.
• Hidden epics. A "small" refactor that ripples through ten files discourages first-timers.
• Issues only the maintainer could do. If it needs context from a private conversation, it is not a first issue.
• Promising fast reviews you cannot give. A PR left for a month loses the contributor.

Example Trigger Phrases

• "Create good first issues for my repo from this roadmap."
• "I want contributors. Write 10 starter issues newcomers can finish."
• "Turn these TODO comments into good first issues with acceptance criteria."
• "Prepare my project for Hacktoberfest-style contributors."