---
name: github-issue-solver
description: Accept a GitHub issue URL or issue details, create a comprehensive plan (in plan mode - shows plan first), then implement the solution including tests and documentation, create/update release notes for Home Assistant users, and update the README roadmap for new features. Use when the user provides a GitHub issue or asks to solve an issue. ALWAYS presents the plan first and waits for user approval before implementing.
---

# 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](https://www.home-assistant.io/docs/), relevant integration pages, or this repo’s published docs (e.g. GitHub Pages) so users can go further.

5. **Example format**:

   ```markdown
   # 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:
     ```markdown
     - [ ] **`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:

````markdown
## 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
```