Positron Issue Creator

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:

1. Be terse - Every word serves a purpose
2. Be fluff-free - No apologies, preambles, or unnecessary politeness
3. Be specific - Exact versions, precise steps, concrete details
4. 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:

1. What - The issue itself (1 sentence)
2. Why - Impact/context (1-2 sentences if not obvious)
3. How - Steps or proposed solution (bullet points)
4. 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'
---