| name | smart-questions |
| description | This skill should be used when the user asks to draft a question to maintainers, draft PR feedback on someone else's in-progress pull request, draft a reply to review comments on their own PR, or draft a claim comment for an issue they want to take. Trigger phrases include: "draft a question to maintainers", "I want to ask about this issue", "draft PR feedback", "help me review this PR", "draft a review reply", "respond to maintainer feedback", "draft a claim comment", "I want to take this issue". All output from this skill is a DRAFT for the user's review — never posted automatically.
|
Smart Questions
Refer to references/smart-questions-principles.md for the full principle set and a good/bad
example pair before drafting any question, comment, or reply.
DRAFT-ONLY Contract
Every piece of outbound text this skill produces is a DRAFT. The contract is:
- Return the complete draft text to the orchestrating
/oss command. The orchestrator saves it
to a .oss-drafts/<scenario>-<owner>-<repo>-<item>-<UTC>.md file using the Write tool, then
presents it to the user.
- After saving, the orchestrator adds the mandatory notice:
DRAFT — saved to <path>. Review and edit this file before sending.
This plugin will NOT post, comment, push, or send anything. Sending is handled by the separate execution/submission plugin.
- NEVER call any tool that posts, comments, pushes, or creates a GitHub resource.
- The user may edit the saved file or cancel the draft before deciding to send it through the
execution plugin.
This contract applies to every scenario below without exception.
Scenario A — Draft Questions for Maintainers (clarify)
To draft clarifying questions for a maintainer about an issue or PR:
- Summarise what is already known from the issue/PR thread, linked docs, and the project's
contributing guide — so questions do not re-ask what is answered.
- Identify the specific gaps or ambiguities in the issue/PR that are worth clarifying (design
intent, scope boundaries, API choices, preferred approach).
- Draft each question following the principles in the references file:
- Research first: cite what was already read.
- Be specific: reference the exact line/section/comment that prompted the question.
- Show prior effort: mention what was tried or considered.
- Ask answerable questions: frame for a concrete answer.
- For each drafted question, note which part of the issue/PR (paragraph, comment, or code
reference) prompted it so the user can judge relevance.
- Do NOT include questions that are already answered in the thread, linked issues, or the
CONTRIBUTING guide.
Scenario B — Draft Feedback on Someone's In-Progress PR (engage)
To draft constructive feedback on another contributor's pull request:
- Confirm the oss-researcher has fetched: the PR description, changed files/diff, CI status,
review status, and the full comment thread.
- Summarise what the PR does and where it currently stands (awaiting review, failing CI, stalled,
needs rebase, etc.).
- Suggest the most useful way the user can help based on the PR's state:
- Failing CI → offer to investigate/reproduce the failure.
- Review-requested → offer a specific-file review.
- Stalled > 30 days → offer to take over or rebase (if appropriate).
- Needs rebase → note the conflicts.
- Draft feedback that is:
- Constructive and specific — grounded in the actual diff and discussion.
- Not dismissive, duplicative, or based on parts of the PR not shown.
- Respectful and professional in tone.
- For large diffs, scope feedback to the most relevant files and state that explicitly.
- Note which part of the diff or discussion each feedback point addresses.
Scenario C — Draft Replies to Review Comments on My PR (review-reply)
To draft replies to maintainer review comments on the user's own pull request:
- For each review comment, draft a reply that:
- Acknowledges the feedback.
- States what the user changed in response OR explains (respectfully) why they disagree.
- Stays concise.
- Does NOT commit to changes the user has not actually made.
- Does NOT fabricate code changes.
- If multiple comments can be grouped (same theme or same file area), offer to draft a combined
reply covering them all.
- Optionally produce a single change-summary comment recapping how this round of feedback was
addressed (desirable per story 6 acceptance criteria).
- Etiquette follows the principles in the references file (acknowledge, state action/rationale,
stay concise, assume good faith).
Scenario D — Draft a Claim Comment (claim)
To draft a claim comment for an issue the user wants to take:
- Confirm the oss-claim-analyst has already assessed the issue as "appears free to take".
If the issue is claimed, do NOT draft a claim comment — switch to Scenario B (engage) instead.
- Note the project's preferred claiming mechanism if known from the contribution norms:
- Some projects prefer a comment ("I'd like to take this").
- Some prefer self-assign (if the contributor has triage permissions).
- Apache projects may use JIRA assignment or a dev@ mailing list thread.
- Draft a polite, brief claim comment following the smart-questions principles:
- Introduce yourself briefly (optional but friendly for first-time contributors).
- State your intent to work on the issue.
- Mention any relevant skills or context that makes you a good fit.
- Ask if there is anything specific the maintainer would like you to keep in mind.
- Keep the draft short (3–5 sentences max). Do not over-promise scope or timeline.
References
See references/smart-questions-principles.md for the full principle list and good/bad examples.
Full guide: https://github.com/ryanhanwu/How-To-Ask-Questions-The-Smart-Way
