gh-issue-improvement

# GitHub Improvement Proposal Generator Skill This skill generates a well-structured improvement/enhancement proposal for GitHub issues based on the conversation context and saves it to `.ai/gh_issues/YYMMDD-<short-issue-name>.md`. This skill is specifically designed for **improvements and enhancements** - not for bug reports or error fixes. ## Purpose When invoked, this skill extracts improvement information from the current conversation and creates a standardized GitHub enhancement proposal document. **Use this skill for:** - Feature enhancements or improvements - Code refactoring or restructuring - Performance optimizations - Architecture improvements - Tool migrations (e.g., migrating MCP tools to `direct_api_call`) - API consolidation or simplification - Documentation improvements - Testing improvements **Do NOT use this skill for:** - Bugs, errors, or broken functionality - Incorrect behavior or unexpected results - System failures or crashes ## Workflow ### 1. Extract Issue Information Review the conversation to identify: - The improvement or enhancement being proposed - Current state and its limitations - Motivation and benefits of the improvement - Proposed changes at a conceptual level - Expected outcomes or impact ### 2. Generate Filename Create a filename using the pattern: ```text .ai/gh_issues/YYMMDD-<short-issue-name-with-dashes>.md ``` Where: - `YYMMDD`: Current date in 2-digit year, month, day format (e.g., `260128` for January 28, 2026) - `<short-issue-name-with-dashes>`: A brief, descriptive name using lowercase letters and dashes (e.g., `migrate-logs-to-direct-api`, `optimize-pagination-logic`, `consolidate-nft-tools`) Example: `.ai/gh_issues/260128-migrate-logs-to-direct-api.md` ### 3. Create Issue Document Write a Markdown document with the following sections: ```markdown # [Brief Title of the Improvement] ## Description [Short description of the improvement - 2-3 sentences summarizing what is being proposed] ## Motivation [Clear explanation of why this improvement is needed - what problems does it solve, what benefits does it provide] ## Current State [Description of how things work currently, including any limitations or pain points] ## Proposed Changes [High-level description of what should change conceptually. Focus on WHAT changes, not HOW to implement them. Avoid step-by-step implementation details, specific file paths, or granular action items. Keep it strategic and outcome-focused.] ## Expected Benefits [List of concrete benefits that will result from this improvement - can include improved performance, better maintainability, reduced complexity, etc.] ``` **Example of well-formed "Proposed Changes" section:** ```markdown ## Proposed Changes - Transition the standalone tool to a handler-based architecture consistent with similar tools - Maintain backward compatibility by preserving the REST API endpoint with deprecation notices - Consolidate response processing logic within the dispatcher pattern - Update all references in documentation and integration examples to reflect the new approach ``` ### 4. Content Guidelines **MUST INCLUDE:** - Short description (2-3 sentences) - Motivation explaining why the improvement is needed - Current state description showing what exists today - Proposed changes (clear, organized list describing what should change) - Expected benefits (concrete outcomes) **MUST NOT INCLUDE:** - Detailed code implementation or snippets - Specific file paths or module names (e.g., `blockscout_mcp_server/tools/direct_api/handlers/x_handler.py`) - Step-by-step implementation checklists (e.g., "1. Create X, 2. Update Y, 3. Delete Z") - Granular action items for each file or component - Function names, decorator names, or code structure details - Line-by-line diffs or patches - Test case implementations or test file locations - Documentation file names or specific sections to update **STYLE GUIDELINES:** - Focus on "what" should change and "why" it matters, not "how" to implement it in detail - Use lists and structured formatting for clarity - Be specific enough to be actionable but general enough to allow implementation flexibility - Avoid prescriptive implementation details - leave room for refinement during development - Keep "Proposed Changes" to 3-6 high-level points maximum - Each point should describe an outcome or conceptual change, not an implementation task **PROPOSED CHANGES - GOOD EXAMPLES:** ✓ "Consolidate transaction-related tools under a unified dispatcher pattern" ✓ "Deprecate the dedicated tool in favor of the generic `direct_api_call` interface" ✓ "Preserve existing response processing logic while relocating it to a handler" ✓ "Update documentation to reflect the new tool architecture" **PROPOSED CHANGES - BAD EXAMPLES:** ✗ "Create handler module at `blockscout_mcp_server/tools/direct_api/handlers/x_handler.py` with `@register_handler` decorator" ✗ "Update REST API in `api/routes.py` to return deprecation response with 410 status code" ✗ "Remove import of `transaction_summary` function from `server.py`" ✗ "Migrate tests: Delete `test_transaction_summary.py` and create new handler tests" ### 5. Output Confirmation After creating the file, confirm: - The full path where the file was created - A brief summary of the improvement documented ## Example Usage When the user says: ```bash /gh-issue-improvement ``` You should: 1. Review the conversation for improvement details 2. Generate filename like `.ai/gh_issues/260128-consolidate-transaction-tools.md` 3. Create the issue document with all required sections 4. Confirm creation with: "Created GitHub improvement proposal at [.ai/gh_issues/260128-consolidate-transaction-tools.md](.ai/gh_issues/260128-consolidate-transaction-tools.md)" ## Example Improvements This skill can document various types of improvements: - **Tool Migration**: Migrating an MCP tool to use `direct_api_call` handler pattern - **Refactoring**: Consolidating duplicate code into shared utilities - **Performance**: Optimizing caching strategies or reducing API calls - **Architecture**: Restructuring modules for better separation of concerns - **API Changes**: Simplifying or consolidating API endpoints - **Testing**: Adding comprehensive test coverage for a module - **Documentation**: Improving inline documentation or user guides ## Notes - The skill is designed for improvements discussed during development planning or code reviews - If insufficient information exists in the conversation, ask the user for clarification before generating the document - **CRITICAL**: Keep proposed changes conceptual and strategic - avoid prescriptive implementation details - Before writing "Proposed Changes", review the GOOD vs BAD examples above to ensure appropriate level of abstraction - Think: "What outcomes do we want?" not "What steps should we take?" - If you find yourself writing file paths, function names, or numbered checklists, you're being too prescriptive - Focus on the value proposition - make it clear why this improvement matters