name

positron-issue-creator

description

This skill should be used when drafting GitHub issues for the Positron repository. It provides workflows for searching duplicates, selecting appropriate labels, gathering complete context through questioning, and writing terse, fluff-free issues that precisely describe what is needed or wrong. The skill prepares issues for manual submission by the user. Use this skill when the user asks to draft or prepare an issue for Positron.

Positron Issue Creator

Purpose

This skill guides the drafting of high-quality GitHub issues for the Positron IDE repository. It ensures issues are:

Thoroughly checked for duplicates before drafting
Properly labeled for efficient triage
Written with complete, specific information
Free of unnecessary fluff and filler
Actionable by the development team
Ready for manual submission by the user

When to Use This Skill

Use this skill when:

User explicitly asks to draft, create, file, or report an issue
User describes a bug or feature request that should be tracked
Drafting documentation or improvement requests
User says "can you draft an issue for..." or similar

Do NOT use this skill for:

Intake rotation duties (use positron-intake-rotation instead)
Responding to existing issues
General Positron development tasks

GitHub Access Policy

Read operations (ALLOWED):

Search for existing issues and discussions via gh CLI
Fetch repository labels via gh CLI
View issue details for duplicate checking
Read any public repository information

Write operations (NOT ALLOWED):

Creating issues directly via gh issue create
Commenting on issues
Modifying labels on existing issues
Any other GitHub write operations

Instead: Prepare issues in markdown files or clipboard-ready format for manual user submission.

Core Workflow

Important: This skill prepares issues for manual submission. It does NOT automatically create GitHub issues. The user maintains full control over submitting to GitHub.

Follow this workflow for every issue drafting request:

1. Gather Complete Context

Before drafting anything, ensure all necessary information is available. Use iterative questioning if needed.

For Bug Reports, obtain:

Positron version (Help > About or specific build number)
Operating system and version
Session details (R/Python version)
Exact steps to reproduce
Expected vs. actual behavior
Error messages (from UI, Output panel, or Developer Console)
Screenshots if relevant

For Feature Requests, obtain:

Clear description of the desired feature
Use case (why it's needed, what problem it solves)
Proposed behavior (how it should work)
Any related issues or examples from other tools

Ask specific questions when information is missing:

"What Positron version are you using? Check Help > About"
"What's the exact error message displayed?"
"What did you expect to happen vs. what actually happened?"
"Can you provide the specific steps to reproduce this?"

Never make assumptions. If unclear, ask rather than guess.

2. Search for Duplicates

Use scripts/search_duplicates.sh to search for existing issues and discussions:

cd /path/to/positron/.claude/skills/positron-issue-creator
./scripts/search_duplicates.sh "keywords from issue"

Review results carefully:

Check both open and closed issues
Look at discussions as well
Consider variations of the search terms

Present findings to user:

Show all potentially related issues
Highlight any that seem very similar
Ask user to confirm whether these are duplicates
For uncertain matches, explicitly ask: "Is this the same issue as #1234?"

If duplicate found:

Inform user that issue already exists
Provide link to existing issue
Suggest they add a comment or 👍 reaction if they want to track it
Do NOT create new issue

If no duplicates:

Proceed to drafting the issue
Reference any related issues in the draft

3. Select Appropriate Labels

Use scripts/fetch_labels.sh to retrieve current repository labels:

cd /path/to/positron/.claude/skills/positron-issue-creator
./scripts/fetch_labels.sh

Choose labels based on:

Area labels (select 1-2):

area: console - Console/REPL functionality
area: notebook - Jupyter notebook integration
area: editor - Text editor functionality
area: plots - Plot viewer and visualization
area: data-explorer - Data viewer and explorer
area: connections - Database connections
area: help - Help pane and documentation
area: ui - General UI/UX issues
Review full list from fetch_labels.sh for complete options

Type label (select 1):

Bug - Something doesn't work as intended
Feature Request - New capability or enhancement
Documentation - Documentation improvements
Performance - Works but too slowly

Other considerations:

Avoid adding priority labels (set during triage)
Don't add status labels (will be set by team)
Multiple area labels are acceptable if issue spans components

4. Draft the Issue

Use the templates in references/issue_templates.md as starting points, but adapt to the specific issue.

Load templates when needed:

Bug reports: Reference bug report structure
Feature requests: Reference feature request structure
Hybrid cases: Adapt as appropriate

Follow writing guidelines from references/writing_guidelines.md:

Core principles:

Be terse - Every word serves a purpose
Be fluff-free - No apologies, preambles, or unnecessary politeness
Be specific - Exact versions, precise steps, concrete details
Be direct - Get to the point immediately

Title guidelines:

Bug: [Component] fails when [condition]
Feature: Add [feature] to [component]
Complete sentence that tells the full story
Scannable and searchable

Body structure:

What - The issue itself (1 sentence)
Why - Impact/context (1-2 sentences if not obvious)
How - Steps or proposed solution (bullet points)
Details - System info, errors, screenshots (as needed)

Example bug report:

Title: Console freezes when printing dataframes with 100k+ rows

The console becomes unresponsive when printing large dataframes.

## Steps to reproduce

1. Create dataframe: `df = pd.DataFrame({'a': range(100000)})`
2. Print it: `print(df)`
3. Console freezes, UI becomes unresponsive

## System details

- Positron 2024.10.0 Build 123
- macOS 14.5
- Python 3.11.6

## Error messages

Developer Console shows: "Maximum call stack size exceeded"

Example feature request:

Title: Add keyboard shortcut to insert markdown cell in notebooks

Currently inserting markdown cells requires clicking the dropdown menu.
Keyboard shortcut would improve notebook authoring workflow.

## Proposed behavior

- Add keyboard shortcut (e.g., Cmd+M or Ctrl+M)
- Should work when focus is in notebook
- Should insert cell below current cell

## Context

Similar to Jupyter's 'M' key in command mode. Notebook workflows
frequently alternate between code and markdown cells.

Common anti-patterns to avoid:

Unnecessary background or preambles
Vague descriptions ("it doesn't work", "sometimes crashes")
Combining multiple unrelated issues
Apologetic or overly polite language
Missing concrete details (exact versions, error messages)
Long-winded explanations when concise ones suffice

Review checklist before presenting:

Title is complete and specific
Body starts with the core issue
Reproduction steps are clear (for bugs)
System details included (for bugs)
Error messages are exact quotes
No unnecessary fluff
Each sentence adds value
Single, focused topic
Appropriate labels selected

5. Present Draft to User

Show the complete drafted issue including:

Title
Full body text
Proposed labels

Ask user: "Does this accurately capture the issue? Would you like any changes before I create it?"

Allow for iteration:

User may want to adjust wording
May remember additional details
May want to emphasize different aspects

Make requested changes and show updated draft.

6. Prepare Issue for Manual Submission

Once user approves the draft, offer options for how they want to use it:

Ask the user: "How would you like me to prepare this issue?"

Option 1: Save to a markdown file
Option 2: Format for clipboard (provide text ready to copy)

Option 1: Save to Markdown File

Create a markdown file with all issue details:

# Create file with timestamp in name for uniqueness
cat > "positron-issue-$(date +%Y%m%d-%H%M%S).md" <<'EOF'
---
title: Issue title here
labels: area: console, Bug
repository: posit-dev/positron
---

Full issue body here
with multiple lines
EOF

After saving:

Show the file path
Remind user to manually create the issue on GitHub
Provide quick link: https://github.com/posit-dev/positron/issues/new

Option 2: Format for Clipboard

Present the issue in a format ready to copy:

**Title:**
Issue title here

**Labels:**
area: console, Bug

**Body:**
Full issue body here
with multiple lines

---
Create this issue at: https://github.com/posit-dev/positron/issues/new

After presenting:

Explain that user should copy this text
Remind them to paste into GitHub's new issue form
Note that they'll need to manually select labels in the UI

Important Guidelines

Duplicate Detection

Be thorough but not pedantic:

Search with multiple keyword combinations
Check both issues and discussions
Look at closed items too (might be fixed or wontfix)

When uncertain:

Show user the potentially similar issues
Ask explicitly: "Is this the same as what you're reporting?"
Err on the side of creating new issues rather than incorrectly marking as duplicate

Context Gathering

Never guess or assume:

If version is unclear, ask specifically
If steps are vague, request clarification
If error message is paraphrased, ask for exact text

Be patient with iteration:

Users may not have all information immediately
May need to reproduce issue to get details
It's better to ask multiple questions than create incomplete issue

Writing Style

Optimize for scanability:

Busy developers need to quickly understand the issue
Put most important information first
Use formatting (headings, lists, code blocks) appropriately

Respect reader's time:

No unnecessary pleasantries beyond "Thanks for reporting"
No apologetic language
No marketing-speak or enthusiasm
Just clear, factual information

Be precise:

Use exact versions, not "latest" or "recent"
Quote error messages exactly
Number steps clearly
State actual behavior, not interpretations

Special Cases

Security Issues

If user describes a security vulnerability:

Do NOT create public issue
Inform user: "This appears to be a security issue. Please report it privately to security@posit.co instead of creating a public issue"
Do NOT proceed with issue creation

Documentation Issues

Treat as feature requests but focus on:

What documentation is missing or incorrect
Where users would look for this information
Suggested improvements

Label with Documentation type.

Performance Issues

Use bug report template but emphasize:

What operation is slow
How long it takes vs. expected time
System details including hardware
Data size or complexity

Label with Performance type.

Multiple Related Issues

If user describes several related but distinct issues:

Identify each separate issue
Explain to user: "This sounds like 3 separate issues. I'll help create each one individually."
Create issues one at a time
Cross-reference in issue bodies if related

Scripts Reference

`scripts/fetch_labels.sh`

Retrieves all repository labels for categorization.

Usage:

./scripts/fetch_labels.sh          # Human-readable output
./scripts/fetch_labels.sh --json   # JSON output for parsing

`scripts/search_duplicates.sh`

Searches for potential duplicate issues and discussions.