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

Step 6: Create/Update Release Notes

1. Release notes format:

   • Create or update a release notes file (check if one exists, otherwise create RELEASE_NOTES.md or similar)
   • Format entries clearly with issue/PR references

2. Release notes structure:

   • Main header: Release title with 2 random emojis at the end
   • Each bug/feature: Use ## heading (level 2) for each bug fix or feature, starting with a relevant emoji
   • Notes under each section: Small descriptive notes under each heading

3. Release notes content:

   • Bug fixes: "Fixed [description] - fixes #[issue-number]"
   • New features: "Added [feature name] - fixes #[issue-number]" (or equivalent plain-language lead)
   • Enhancements: "Improved [description] - fixes #[issue-number]"
   • Breaking changes: Clearly mark with "⚠️ BREAKING CHANGE:" prefix
   • Do not thank contributors in release notes — appreciation belongs in the README roadmap (Step 7), not in RELEASE_NOTES.md.

4. Tone and links:

   • Prefer short, user-facing copy; avoid deep technical detail (file names, internal APIs) unless necessary for migration.
   • Link where it helps: Home Assistant documentation, relevant integration pages, or this repo’s published docs (e.g. GitHub Pages) so users can go further.

5. Example format:

   # Hidden Entity Filtering & Dark Mode!🎉✨
   
   ## 🔍 Hidden Entity Filtering
   
   Hidden entities are now filtered out to match Home Assistant’s more-info behavior - fixes #43
   
   ## 🌙 Dark Mode Support
   
   Dark mode option for low-light dashboards - fixes #123
   
   See [Home Assistant themes](https://www.home-assistant.io/integrations/frontend/) for related settings.
   

6. Home Assistant user-friendly language:

   • Write in clear, non-technical language
   • Focus on what users can do or what problems are solved
   • Avoid internal implementation details
   • Use Home Assistant terminology where appropriate

Step 7: Update README Roadmap (for New Features)

1. Check if it's a new feature:

   • If the issue is a feature request or adds new functionality
   • If it's a bug fix, skip this step

2. Add to roadmap:

   • Locate the "Project Roadmap" section in README.md
   • Add a new entry in the format:

     - [ ] **`Feature Name`**: Description of feature - thanks @[username]
     

   • Use present tense for completed features (change [ ] to [x] after implementation)
   • Use future tense for planned features

3. Thank the contributor:

   • If the issue was opened by a GitHub user, include their username
   • Format: - thanks @[username]
   • If multiple contributors, list them all

Step 8: Final Checklist

Before completing, verify:

• All code changes are implemented
• All tests are written and passing
• Test quality: Reviewed test files for duplicative or low-value tests that could be removed
• Test reuse: Confirmed that existing test setup/mocks were reused where possible
• Documentation is updated (README.md, code comments)
• Release notes are created/updated
• README roadmap is updated (if new feature)
• Code follows project style guidelines
• TypeScript types are correct
• No linter errors
• Translation files updated (if needed)

Step 9: Summary

Provide a summary of:

• What was implemented
• Files created/modified
• Test coverage added
• Documentation updates
• Release notes entry
• Roadmap update (if applicable)

Notes

• CRITICAL: This skill operates in PLAN MODE - always present the plan first and wait for user approval
• Never implement code changes without showing the plan and getting user confirmation
• Always maintain consistency with existing code patterns
• Follow the project's TypeScript and testing conventions
• Ensure backward compatibility unless it's a breaking change
• Consider Home Assistant version compatibility
• Test with multiple browsers if UI changes are involved
• Release notes (RELEASE_NOTES.md): user-facing, no contributor thanks (those go in the README roadmap); include links to Home Assistant or project docs where relevant; avoid unnecessary technical detail

Plan Presentation Format

When presenting the plan, use this structure:

## Plan for Issue #[number]: [Title]

### Issue Summary

[Brief summary of what needs to be done]

### Files to Create/Modify

- `path/to/file1.ts` - [what will change]
- `path/to/file2.ts` - [what will change]
- ...

### Implementation Approach

[High-level description of how you'll implement the solution]

### Test Strategy

- Test file: `test/path/to/file1.spec.ts`
  - **Prefer updating existing tests** rather than creating many new test cases
  - **Reuse existing setup/mocks**: [describe what existing mocks or setup will be reused]
  - If updating existing test: [which test and what will be added]
  - If new test needed: [brief description of why and what it covers, and how it reuses existing setup]
  - Aim for 1-2 focused test cases total
  - **Review test file**: Check for any duplicative or low-value tests that could be removed or consolidated

### Documentation Updates

- README.md: [what sections will be updated]
- Code comments: [what will be documented]
- Translations: [if applicable]

### Release Notes Draft

```markdown
## [Emoji] [Feature/Bug Name]

Brief description, optional YAML example, links to HA or project docs; no contributor thanks; fixes issue when applicable.
```

Roadmap Entry Draft (if new feature)

[Draft of the roadmap entry]

Ready to proceed? Please review the plan above and let me know if you'd like me to continue with implementation.

## Example Workflow

1. User provides: "Solve issue #123: Add dark mode support"
2. Fetch issue details from GitHub
3. **PLAN MODE**: Create comprehensive plan:
   - Files to modify: `src/cards/device-card/styles.ts`, `src/cards/device-card/types.ts`, `src/cards/device-card/editor.ts`
   - Tests: Update existing test in `test/cards/device-card/card.spec.ts` to include dark mode scenarios (prefer updating over creating new tests)
   - Documentation: Update README.md Features section, add config option to table
   - Release notes draft: "## Dark Mode Support\n\nAdded dark mode theme option - fixes #123" (no thanks; link to HA docs if useful)
   - Roadmap draft: "- [ ] **`Dark mode support`**: Add dark mode theme option - thanks @username"
4. **PRESENT PLAN TO USER** - Wait for approval
5. **ONLY AFTER APPROVAL**: Implement code changes
6. **ONLY AFTER APPROVAL**: Create/update test files
7. **ONLY AFTER APPROVAL**: Update documentation
8. **ONLY AFTER APPROVAL**: Create/update release notes
9. **ONLY AFTER APPROVAL**: Update roadmap
10. Summary: List all changes made

Source: homeassistant-extras/device-card — distributed by TomeVault.