Open-source first-issue readiness
Sort one GitHub or GitLab issue by whether it is ready to label as a good first issue: ready to label, needs a narrower scope, needs a starter patch or test, keep with maintainers, or not a starter task, so maintainers stop pointing newcomers at tickets they cannot finish.
F@fLimits to keep in mind
This is guidance for maintainers, not a promise that a contributor will have a pull request accepted.
Every project has its own review, license and security rules; follow those when they are stricter than this label.
A newcomer still needs a timely review; labeling alone is not enough.
Problem
Maintainers want new contributors to take a first issue, but many tickets marked 'good first issue' are too vague, need hidden context, touch risky code, or have gone stale. Newcomers open unfinished pull requests, wait weeks for clarification, or leave; maintainers then spend more time coaching than they would have spent fixing the ticket themselves.
Goal
Label each issue so clear, small, well-specified tasks can be marked as a good first issue, vague ones are narrowed, tasks that need a failing test or starter patch are prepared first, risky or core work stays with maintainers, and anything that is not a starter task is labeled honestly, with a human deciding when the report is incomplete.
Input / state
One issue: its title and description, the kind of change, how clearly a newcomer could start, and any labels, linked code or previous attempts.
- issue_text
- The issue title and the body as written, including acceptance criteria, screenshots or error messages if present.
- change_type
- What the issue appears to ask for: typo or docs, copy, a small UI change, a bug with a known cause, a refactor, a feature, or infrastructure.
- starter_signals
- Hints a newcomer would use: file or function names, a failing test, reproduction steps, links to similar pull requests, or a note that a maintainer will review quickly.
- risks_and_history
- Optional: area of the codebase, tests around it, security or data impact, how old the issue is, earlier pull requests, or discussion that went quiet.
Decision question
first_issue_readinessHow ready is this issue to offer as a good first issue? Use ready_to_label when a newcomer can finish a small, well-specified change with the pointers already in the ticket. Use needs_narrower_scope when the idea is fine but too broad or vague. Use needs_starter_patch when a failing test, reproduction or skeleton change is missing. Use keep_with_maintainers for risky, core, stale or design-heavy work. Use not_a_starter_task for questions, duplicates, discussions or large features. Use needs_review when the ticket is too thin to judge.
Options
ready_to_labelA small, low-risk change with a clear expected result and enough pointers (file, function, reproduction or similar pull request) that a newcomer can open a focused pull request without a long design thread.needs_narrower_scopeThe request is real, but it covers several files, several bugs, or an open-ended improvement. A maintainer should split or rewrite it into one concrete change before labeling it for newcomers.needs_starter_patchThe task could be a first issue once a maintainer adds a failing test, a minimal reproduction, or a skeleton patch that shows where to edit; without that, a newcomer would have to discover the codebase first.keep_with_maintainersThe work belongs with people who already know the project: security or data handling, a core API, a flaky or untested area, a long-stale ticket, or a change that needs a design decision.not_a_starter_taskThis is not a first contribution: a support question, a duplicate, a feature request that needs an RFC, a dependency bump with wide fallout, or a discussion with no agreed change.
Allowed outcomes
Decided in your code from the answer and its confidence. Thresholds are yours to set and test.
- Ask a maintainer to lookConfidence is below your threshold, the issue body is too thin to judge, or the report is not about a project issue.
- Label it a good first issueChoice is ready_to_label and confidence meets your threshold.
- Narrow or split the ticket firstChoice is needs_narrower_scope and confidence meets your threshold.
- Add a test or starter patch firstChoice is needs_starter_patch and confidence meets your threshold.
- Keep this with maintainersChoice is keep_with_maintainers and confidence meets your threshold.
- Do not use as a first issueChoice is not_a_starter_task and confidence meets your threshold.
Example scenarios
Predefined demonstrations. No model is called; the outcome shown is an illustrative judgment.
Example state
{
"issue_text": "Title: Typo in README install command. Body: Line 42 says 'npm run startx' but the script is 'npm start'. Please fix that one line.",
"change_type": "Docs typo in the root README",
"starter_signals": "Exact file and line given; one-line change",
"risks_and_history": "Opened yesterday, no earlier pull request"
}Outcome
IllustrativeChoice is ready_to_label and confidence meets your threshold.
Why
A single documented typo with a file and line is a classic ready first issue.
Using it well
- A good first issue should be completable in a few hours: one idea, a clear done-when, and a pointer to the file or failing path. Prefer docs, copy, typo, small UI, or a well-reproduced shallow bug.
- Do not label work that needs a design decision, a security review, a data migration, or changes across many packages, even if someone added a 'good first issue' label in the past.
- If the issue is older than a few months, check that the file names and advice still match the default branch before calling it ready.
- If reproduction is missing or the bug only happens in an area with no tests, ask for a failing test or a starter patch rather than sending a newcomer in blind.
- Leave a welcome comment with the expected first step and who will review, so the ticket is not only labeled but actually supported.
- If the report looks like a user support question, a duplicate, or something other than a repo issue, use not_a_starter_task or needs_review instead of inventing a task.
Request definition
POST https://api.typesafe.ai/v1/systemone{
"model": "jev-latest",
"state": {
"issue_text": "<issue_text>",
"change_type": "<change_type>",
"starter_signals": "<starter_signals>",
"risks_and_history": "<risks_and_history>"
},
"questions": {
"first_issue_readiness": {
"type": "choice",
"instructions": "How ready is this issue to offer as a good first issue? Use ready_to_label when a newcomer can finish a small, well-specified change with the pointers already in the ticket. Use needs_narrower_scope when the idea is fine but too broad or vague. Use needs_starter_patch when a failing test, reproduction or skeleton change is missing. Use keep_with_maintainers for risky, core, stale or design-heavy work. Use not_a_starter_task for questions, duplicates, discussions or large features. Use needs_review when the ticket is too thin to judge.",
"criteria": {
"ready_to_label": "A small, low-risk change with a clear expected result and enough pointers (file, function, reproduction or similar pull request) that a newcomer can open a focused pull request without a long design thread.",
"needs_narrower_scope": "The request is real, but it covers several files, several bugs, or an open-ended improvement. A maintainer should split or rewrite it into one concrete change before labeling it for newcomers.",
"needs_starter_patch": "The task could be a first issue once a maintainer adds a failing test, a minimal reproduction, or a skeleton patch that shows where to edit; without that, a newcomer would have to discover the codebase first.",
"keep_with_maintainers": "The work belongs with people who already know the project: security or data handling, a core API, a flaky or untested area, a long-stale ticket, or a change that needs a design decision.",
"not_a_starter_task": "This is not a first contribution: a support question, a duplicate, a feature request that needs an RFC, a dependency bump with wide fallout, or a discussion with no agreed change."
}
}
}
}Request shape from the System One API reference; a Kev server accepts the same body. Replace the placeholder state with your data. Requests need your own API key or server.
Version History
Initial version