Add 20 comprehensive issue templates with automation tooling

.github/ISSUES/01-unit-tests-useFetchStories.md

@@ -0,0 +1,62 @@
+---
+title: Add unit tests for useFetchStories hook
+labels: testing, enhancement, good-first-issue
+---
+
+## Description
+
+Create comprehensive unit tests for the `useFetchStories` custom hook to test caching logic, error handling, and API response handling.
+
+## Background
+
+Currently, the project README mentions Jest and React Testing Library but no test files exist in the repository. The `useFetchStories` hook has complex caching logic with ETag support and localStorage fallback that needs thorough testing to ensure reliability.
+
+## Requirements
+
+Tests should cover the following scenarios:
+
+1. **Successful API fetch**
+   - Fetches stories from DEV.to API successfully
+   - Sorts stories by published date
+   - Updates state correctly
+
+2. **Cache hit scenario**
+   - Returns cached data when cache is valid (within 5 minutes)
+   - Doesn't make API call when cache is fresh
+
+3. **Cache miss scenario**
+   - Makes API call when cache is expired
+   - Updates cache with new data
+
+4. **304 Not Modified response**
+   - Handles ETag-based cache validation
+   - Uses cached data when server returns 304
+
+5. **Error states**
+   - Handles API errors gracefully
+   - Sets appropriate error messages
+   - Falls back to expired cache when available
+
+6. **Expired cache fallback**
+   - Uses stale cache data when API fails
+   - Shows error message but displays cached content
+
+## Technical Details
+
+- File location: `hooks/useFetchStories.ts`
+- Test framework: Jest
+- Testing library: React Testing Library / React Hooks Testing Library
+- Mock localStorage and fetch API
+
+## Acceptance Criteria
+
+- [ ] Test file created at `hooks/useFetchStories.test.ts`
+- [ ] All 6 scenarios covered with tests
+- [ ] Tests pass successfully
+- [ ] Code coverage for the hook is above 90%
+- [ ] Tests are well-documented with clear descriptions
+
+## Related Files
+
+- `hooks/useFetchStories.ts` - Hook to be tested
+- `types/index.ts` - Type definitions used by the hook

.github/ISSUES/02-e2e-tests-playwright.md

@@ -0,0 +1,83 @@
+---
+title: Add comprehensive E2E tests with Playwright
+labels: testing, enhancement, infrastructure
+---
+
+## Description
+
+Implement end-to-end testing suite using Playwright to test critical user flows and prevent regressions.
+
+## Background
+
+Currently, no E2E tests exist despite having critical user flows like story navigation, mini-game interaction, and API error handling. E2E tests would ensure quality before deployment and catch integration issues early.
+
+## Requirements
+
+### Test Coverage
+
+1. **Story Navigation Flow**
+   - Load application and verify stories are displayed
+   - Navigate forward through stories
+   - Navigate backward through stories
+   - Verify story counter updates correctly
+
+2. **Mini-Game Interaction**
+   - Toggle mini-game visibility
+   - Start the game
+   - Use arrow keys to move player
+   - Verify collision detection
+   - Check score updates
+
+3. **API Error Handling**
+   - Mock API failures
+   - Verify error messages are displayed
+   - Verify fallback to cached data works
+
+4. **Caching Behavior**
+   - Verify localStorage caching
+   - Test cache expiration
+   - Test ETag-based validation
+
+5. **Accessibility Features**
+   - Test keyboard navigation
+   - Verify ARIA labels
+   - Test focus management
+
+6. **Responsive Design**
+   - Test on mobile viewport
+   - Test on tablet viewport
+   - Test on desktop viewport
+
+## Technical Details
+
+- Install Playwright: `npm install -D @playwright/test`
+- Create test configuration: `playwright.config.ts`
+- Create test directory: `e2e/` or `tests/e2e/`
+- Add script to package.json: `"test:e2e": "playwright test"`
+
+## Acceptance Criteria
+
+- [ ] Playwright installed and configured
+- [ ] All 6 test categories implemented
+- [ ] Tests pass on Chromium, Firefox, and WebKit
+- [ ] GitHub Actions workflow includes E2E tests
+- [ ] Test reports generated and accessible
+- [ ] README updated with testing instructions
+
+## CI/CD Integration
+
+Add to `.github/workflows/nextjs.yml`:
+```yaml
+- name: Install Playwright Browsers
+  run: npx playwright install --with-deps
+
+- name: Run E2E tests
+  run: npm run test:e2e
+```
+
+## Related Files
+
+- `app/page.tsx` - Main page component
+- `components/StoryCard.tsx` - Story display component
+- `components/MiniGame.tsx` - Mini-game component
+- `hooks/useFetchStories.ts` - Data fetching logic

.github/ISSUES/03-loading-skeleton-storycard.md

@@ -0,0 +1,94 @@
+---
+title: Add loading skeleton for StoryCard component
+labels: enhancement, ui/ux, performance
+---
+
+## Description
+
+Replace the simple "Loading stories..." text with an animated skeleton loader that matches the StoryCard layout to improve perceived performance.
+
+## Background
+
+Currently, when stories are loading, users see only plain text saying "Loading stories...". A skeleton loader provides visual feedback about the layout structure and creates a better perceived performance, making the app feel faster and more polished.
+
+## Requirements
+
+### Skeleton Structure
+
+The skeleton should include placeholders for:
+1. **Header section**
+   - Title placeholder (2-3 lines)
+   - XP badge placeholder
+
+2. **Content section**
+   - Description placeholder (4-5 lines)
+
+3. **Author section**
+   - Avatar placeholder (circular, 48x48px)
+   - Author name placeholder (1 line)
+   - Username placeholder (1 line)
+
+4. **Footer section**
+   - Progress bar placeholder
+   - Navigation buttons placeholders
+   - Level indicator placeholder
+
+### Animation
+
+- Use CSS shimmer/pulse animation effect
+- Animation should be smooth and subtle
+- **Must respect `prefers-reduced-motion`** - no animation for users who prefer reduced motion
+
+## Technical Details
+
+**Option 1: Pure CSS Implementation**
+```css
+.skeleton {
+  background: linear-gradient(
+    90deg,
+    var(--skeleton-base) 0%,
+    var(--skeleton-highlight) 50%,
+    var(--skeleton-base) 100%
+  );
+  background-size: 200% 100%;
+  animation: shimmer 1.5s infinite;
+}
+
+@keyframes shimmer {
+  0% { background-position: -200% 0; }
+  100% { background-position: 200% 0; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .skeleton {
+    animation: none;
+  }
+}
+```
+
+**Option 2: Use a library**
+- `react-loading-skeleton` or similar
+
+## Acceptance Criteria
+
+- [ ] Create `SkeletonCard` component or skeleton variant of `StoryCard`
+- [ ] Skeleton matches the actual `StoryCard` layout
+- [ ] Smooth shimmer/pulse animation implemented
+- [ ] Animation respects `prefers-reduced-motion`
+- [ ] Skeleton shown during initial load
+- [ ] Skeleton shown when refetching stories
+- [ ] Works well with dark/light themes (if theme toggle exists)
+- [ ] No layout shift when skeleton is replaced with actual content
+
+## Design Considerations
+
+- Use existing CSS variables for colors
+- Skeleton should be subtle, not distracting
+- Border radius should match actual card
+- Spacing should match actual card layout
+
+## Related Files
+
+- `components/StoryCard.tsx` - Main card component
+- `app/page.tsx` - Page that shows loading state
+- `components/StoryCard.module.css` - Card styles

.github/ISSUES/04-bundle-optimization-code-splitting.md

@@ -0,0 +1,114 @@
+---
+title: Optimize bundle size and implement code splitting
+labels: performance, enhancement, optimization
+---
+
+## Description
+
+Analyze and optimize bundle size using next/bundle-analyzer to improve initial load time and Core Web Vitals scores.
+
+## Background
+
+Currently, no bundle analysis is configured, and all components load upfront. The MiniGame component, in particular, is loaded even when not used, increasing the initial bundle size unnecessarily.
+
+## Requirements
+
+### 1. Bundle Analysis Setup
+
+Install and configure `@next/bundle-analyzer`:
+```bash
+npm install --save-dev @next/bundle-analyzer
+```
+
+Configure in `next.config.mjs`:
+```javascript
+import bundleAnalyzer from '@next/bundle-analyzer';
+
+const withBundleAnalyzer = bundleAnalyzer({
+  enabled: process.env.ANALYZE === 'true',
+});
+
+export default withBundleAnalyzer({
+  // ... existing config
+});
+```
+
+Add script to `package.json`:
+```json
+"analyze": "ANALYZE=true npm run build"
+```
+
+### 2. Dynamic Imports
+
+Implement dynamic imports for components that are:
+- Not needed on initial render
+- Behind user interaction
+- Heavy/large components
+
+**Priority: MiniGame component**
+```tsx
+const MiniGame = dynamic(() => import('../components/MiniGame').then(mod => ({ default: mod.MiniGame })), {
+  loading: () => <div>Loading game...</div>,
+  ssr: false
+});
+```
+
+### 3. Image Optimization
+
+Ensure all images are properly optimized:
+- Use `next/image` consistently (already done for profile images)
+- Optimize SVG files in `/public`
+- Consider using WebP format where appropriate
+
+### 4. Dependency Audit
+
+Review and optimize dependencies:
+- Check for unused dependencies
+- Look for lighter alternatives to heavy libraries
+- Ensure proper tree-shaking
+
+### 5. Route-Based Code Splitting
+
+Verify Next.js automatic code splitting is working:
+- Check each route has its own bundle
+- Verify shared chunks are optimized
+
+## Target Metrics
+
+- **Initial bundle size**: < 200KB (gzipped)
+- **First Contentful Paint (FCP)**: < 1.8s
+- **Largest Contentful Paint (LCP)**: < 2.5s
+- **Time to Interactive (TTI)**: < 3.8s
+
+## Acceptance Criteria
+
+- [ ] Bundle analyzer installed and configured
+- [ ] Analysis script added to package.json
+- [ ] MiniGame component dynamically imported
+- [ ] Bundle analysis report generated and reviewed
+- [ ] Identified and removed unused dependencies (if any)
+- [ ] Documentation added explaining bundle optimization strategy
+- [ ] Performance improvements measured and documented
+- [ ] Core Web Vitals scores improved
+
+## Implementation Steps
+
+1. Install and configure bundle analyzer
+2. Run initial analysis to establish baseline
+3. Implement dynamic import for MiniGame
+4. Re-run analysis to measure improvement
+5. Identify other optimization opportunities
+6. Document findings and results
+
+## Related Files
+
+- `next.config.mjs` - Next.js configuration
+- `package.json` - Dependencies and scripts
+- `app/page.tsx` - Main page (imports MiniGame)
+- `components/MiniGame.tsx` - Component to be dynamically loaded
+
+## Resources
+
+- [Next.js Bundle Analyzer](https://www.npmjs.com/package/@next/bundle-analyzer)
+- [Next.js Dynamic Imports](https://nextjs.org/docs/advanced-features/dynamic-import)
+- [Web Vitals](https://web.dev/vitals/)