GitHub Issue Solver

GitHub Issue Solver

This skill guides you through solving GitHub issues for the Home Assistant device-card project. It ensures comprehensive planning, testing, documentation, and release notes.

When to Use

• Use this skill when the user provides a GitHub issue URL or issue details
• Use when asked to solve, fix, or implement something from a GitHub issue
• Use when planning work based on an issue or feature request

Instructions

IMPORTANT: This skill runs in PLAN MODE first. You MUST present a comprehensive plan to the user and wait for their approval before implementing any code changes.

Step 1: Analyze the GitHub Issue

1. Fetch the issue details:

   • If a GitHub issue URL is provided, fetch it using the web fetch tool or ask the user for the issue details
   • Extract key information:
     • Issue title and description
     • Issue type (bug fix, feature request, enhancement, etc.)
     • Labels and milestones
     • Comments and discussion
     • Related issues or PRs

2. Understand the requirements:

   • Identify what needs to be fixed or implemented
   • Note any edge cases or special considerations mentioned
   • Check if there are any related issues or dependencies

Step 2: Create and Present the Plan (STOP HERE - DO NOT IMPLEMENT YET)

1. Break down the work:

   • List all files that need to be created or modified
   • Identify the core functionality changes required
   • Note any dependencies or related components
   • Review existing code patterns in the project for consistency

2. Create a comprehensive task list:

   • Use the todo_write tool to create a structured task list with all tasks marked as "pending"
   • Include detailed tasks for:
     • Code implementation (specific files and functions)
     • Test creation/updates (specific test files and test cases)
     • Documentation updates (specific sections and files)
     • Release notes (draft the entry)
     • README roadmap update (if new feature, draft the entry)

3. Present the plan to the user:

   • CRITICAL: You MUST stop here and present the complete plan
   • Show a clear, formatted plan including:
     • Summary of the issue and what needs to be done
     • List of files to be created/modified
     • Overview of code changes needed
     • Test strategy and test cases
     • Documentation updates planned
     • Draft release notes entry
     • Draft roadmap entry (if new feature)
   • Wait for user approval before proceeding to Step 3
   • Use language like: "Here's my plan. Please review and let me know if you'd like me to proceed with implementation."

Step 3: Implement the Solution (ONLY AFTER USER APPROVAL)

DO NOT proceed to this step until the user has reviewed and approved the plan from Step 2.

1. Code changes:

   • Follow TypeScript best practices
   • Match the existing code style (check .prettierrc for formatting)
   • Ensure type safety (check tsconfig.json)
   • Follow the project's file structure conventions

2. Key areas to consider:

   • src/cards/ - Card implementations
   • src/delegates/ - Business logic and data retrieval
   • src/html/ - HTML rendering components
   • src/hass/ - Home Assistant integration code
   • src/common/ - Shared utilities
   • src/types/ - TypeScript type definitions

Step 4: Write Tests

1. Test coverage:

   • PREFER updating existing tests over creating many new test cases
   • When possible, add assertions to existing tests that already cover similar functionality
   • Create or update test files in test/ directory matching the source structure
   • Follow existing test patterns (check test/ directory for examples)
   • Use Mocha test framework (check .mocharc.json and mocha.setup.ts)

2. Test requirements:

   • Keep tests concise: Aim for 1-2 focused test cases, or update existing tests to cover multiple scenarios
   • Unit tests for new functions and methods
   • Edge case testing (when necessary, but consolidate into existing tests when possible)
   • Integration tests if applicable
   • Ensure tests pass: yarn test or npm test

3. Test file naming:

   • Test files should match source files with .spec.ts extension
   • Example: src/cards/device-card/card.ts → test/cards/device-card/card.spec.ts

4. Test consolidation strategy:

   • Reuse existing setup/mocks: Before creating new test cases, check if existing tests already have similar mocks, stubs, or setup code that can be reused
   • Review existing tests to see if new functionality can be tested alongside existing assertions
   • Update existing test data/mocks to include new scenarios rather than creating separate tests
   • Only create new test cases when the functionality is truly distinct and cannot be tested within existing tests
   • Avoid duplicating setup code: If multiple tests need similar mocks or stubs, consider:
     • Adding shared setup to beforeEach hooks
     • Extending existing mock data structures
     • Creating helper functions for common test setup

5. Test quality review:

   • Review the entire test file after making changes to ensure:
     • No duplicative tests that test the same thing in slightly different ways
     • No low-value tests that don't add meaningful coverage
     • Tests are well-organized and follow the existing patterns
     • Setup code is not unnecessarily duplicated across tests
   • If you notice duplicative or low-value tests while working, consider removing or consolidating them
   • Focus on tests that provide real value: catching bugs, ensuring correctness, and documenting expected behavior

Step 5: Update Documentation

1. README.md updates:

   • If adding a new feature, add it to the "Features" section
   • Update "Configuration Options" table if adding new config options
   • Add example configurations in "Example Configurations" section
   • Update the "Project Roadmap" section (see Step 7)

2. Code comments:

   • Add JSDoc comments for public functions and classes
   • Document complex logic and algorithms
   • Explain non-obvious decisions

3. Translation files (if adding user-facing strings):

   • Update src/translations/en.json (English)
   • Consider updating other language files: fr.json, pt.json, ru.json
   • Follow the existing translation structure