Issue Management

Purpose

Create well-structured, actionable GitHub issues that facilitate clear communication, efficient triage, and effective task delegation to specialized agents or team members.

Core Principles

Clarity First: Issue title and description must be immediately understandable
Actionable: Clear acceptance criteria and definition of done
Properly Labeled: Use labels for type, priority, area, and agent assignment
Traceable: Link to related issues, PRs, and documentation
Evidence-Based: Include screenshots, logs, or reproduction steps
Agent-Optimized: Structure issues for Copilot agent assignment

Issue Structure

Title Format

[Type] Brief, actionable description (50-80 chars)

Examples:
✅ [Bug] Homepage mobile navigation broken on Safari
✅ [Feature] Add voting discipline dashboard
✅ [Security] Update CSP header for CDN resources
✅ [Accessibility] Fix color contrast in party cards
✅ [Documentation] Update ARCHITECTURE.md with C4 diagrams

Body Template

## Problem Statement
Clear description of the issue or need (2-3 sentences)

## Current Behavior (for bugs)
What happens now (include error messages, screenshots)

## Expected Behavior
What should happen

## Steps to Reproduce (for bugs)
1. Navigate to...
2. Click on...
3. Observe...

## Acceptance Criteria
- [ ] Criterion 1 (testable, verifiable)
- [ ] Criterion 2
- [ ] Criterion 3

## Technical Context
- Affected files: `index.html`, `styles.css`
- Browser/Device: Chrome 120, Safari 17 on iOS 17
- Related issues: #123, #456

## Evidence
[Screenshots, logs, error messages]

## Suggested Solution (optional)
Brief technical approach if known

## Agent Assignment (if applicable)
Recommend: @security-architect, @frontend-specialist

Label Categories

Type Labels (Required)

bug 🐛 - Something isn't working
feature ✨ - New functionality
enhancement 🚀 - Improvement to existing feature
security 🔒 - Security-related issue
documentation 📝 - Documentation changes
accessibility ♿ - WCAG 2.1 AA compliance
performance ⚡ - Speed, optimization
refactor 🔧 - Code quality, technical debt

Priority Labels

priority:critical 🔴 - Blocking, security, data loss
priority:high 🟠 - Major functionality broken
priority:medium 🟡 - Important but not urgent
priority:low 🟢 - Nice to have, future

Area Labels

area:frontend - HTML/CSS/UI changes
area:ci-cd - GitHub Actions, workflows
area:security - Security controls, ISMS
area:accessibility - WCAG compliance
area:i18n - Multi-language support
area:docs - Documentation

Agent Labels (for delegation)

agent:security-architect - Security architecture tasks
agent:frontend-specialist - HTML/CSS/UI tasks
agent:quality-engineer - Validation, testing tasks
agent:documentation-architect - Documentation tasks
agent:isms-compliance-manager - Compliance tasks
agent:deployment-specialist - CI/CD tasks
agent:intelligence-operative - Political data analysis
agent:task-agent - Product management, issue creation
agent:ui-enhancement-specialist - UI/UX enhancements

Status Labels

status:triaged - Reviewed and prioritized
status:blocked - Waiting on dependency
status:in-progress - Actively being worked on
status:needs-review - Ready for review
status:wontfix - Will not be addressed

When to Use

Bug Reports: User-reported or automated test failures
Feature Requests: New functionality needs
Security Issues: Vulnerabilities, compliance gaps
Accessibility Issues: WCAG violations
Technical Debt: Refactoring, code quality
Documentation Needs: Missing or outdated docs
Agent Task Delegation: Assign specialized agents
Product Backlog: Track feature roadmap

Examples

Good Pattern: Bug Report with Evidence

# [Bug] Mobile navigation menu not closing on link click (iOS Safari)

## Problem Statement
On iOS Safari, clicking navigation links does not close the mobile menu, forcing users to manually close it or scroll past it.

## Current Behavior
1. Open mobile menu (☰ button)
2. Click any navigation link
3. Page scrolls to section
4. Menu remains open, obscuring content

## Expected Behavior
Menu should auto-close after link click, revealing content immediately.

## Steps to Reproduce
1. Open https://riksdagsmonitor.com on iPhone (iOS 17)
2. Tap hamburger menu (☰)
3. Tap "Overview" link
4. Observe menu stays open

## Acceptance Criteria
- [ ] Menu closes immediately after link click
- [ ] Behavior consistent across all 14 language versions
- [ ] Works on iOS Safari, Chrome mobile, Firefox mobile
- [ ] No JavaScript errors in console
- [ ] Passes manual accessibility test (keyboard nav)

## Technical Context
- Affected files: `index*.html` (all 14 language versions)
- Browser: Safari 17 on iOS 17.2
- Related: Navigation uses CSS-only implementation

## Evidence
![Screenshot showing open menu after link click](screenshot.png)

## Suggested Solution
Add JavaScript event listener for link clicks to toggle menu:
```javascript
document.querySelectorAll('.nav-link').forEach(link => {
  link.addEventListener('click', () => {
    document.querySelector('.menu-toggle').checked = false;
  });
});

Agent Assignment

Recommend: @frontend-specialist


**Labels**: `bug`, `priority:high`, `area:frontend`, `area:i18n`, `agent:frontend-specialist`

### Good Pattern: Feature Request
```markdown
# [Feature] Add voting discipline dashboard for 8 parliamentary parties

## Problem Statement
Users cannot easily visualize voting discipline metrics (party cohesion, rebels, cross-party votes) for the 8 Swedish parliamentary parties, reducing transparency.

## Expected Behavior
New dashboard page showing:
- Party cohesion percentage (progress bars)
- Number of unanimous votes per party
- Number of rebel votes per party
- Heat map of cross-party voting patterns
- Historical trend over current riksmöte

## Acceptance Criteria
- [ ] Dashboard accessible from main navigation
- [ ] Visualizations use CSS-only (no JavaScript charts)
- [ ] WCAG 2.1 AA compliant (4.5:1 contrast, screen reader support)
- [ ] Responsive design (mobile/tablet/desktop)
- [ ] Available in all 14 languages
- [ ] Data sourced from riksdag-regering-mcp
- [ ] Includes data quality disclaimer

## Technical Context
- New files: `voting-discipline.html`, `voting-discipline_sv.html`, etc.
- Data source: `riksdag-regering-mcp` (search_voteringar, get_voting_group)
- Styling: Cyberpunk theme, use existing CSS variables
- Integration: Link from homepage, add to navigation

## Dependencies
- riksdag-regering-mcp MCP server (already configured)
- political-data-visualization skill
- Party color palette (already defined in styles.css)

## Agent Assignment
Recommend: @intelligence-operative (data analysis) → @ui-enhancement-specialist (UI implementation)

Labels: feature, priority:medium, area:frontend, agent:intelligence-operative, agent:ui-enhancement-specialist

Anti-Pattern: Vague Issue

# Navigation doesn't work

The menu is broken. Please fix it.

Problems:

❌ No clear problem statement
❌ No reproduction steps
❌ No acceptance criteria
❌ No technical context
❌ No evidence (screenshots, logs)
❌ No labels or assignment

Anti-Pattern: Missing Acceptance Criteria

# [Feature] Improve dashboard

Make the dashboard better and faster.

## Description
The current dashboard could be improved in various ways.