# Issue List and Detail Views - Design Prototype

## Overview
The Issue Management interface provides a comprehensive view of project issues synced from Gitea. Users can filter, sort, search, and manage issues. The detail view shows full issue content, status workflow, and activity timeline. Issues are the primary unit of work that agents execute.

## User Stories
- As a user, I want to see all issues in a filterable list so I can find specific work items
- As a user, I want to filter by status, priority, sprint, and assignee to focus on relevant issues
- As a user, I want to sort issues by different criteria to organize my view
- As a user, I want to perform bulk actions on multiple issues efficiently
- As a user, I want to see the sync status to know if issues are current with Gitea
- As a user, I want to view full issue details including description (markdown)
- As a user, I want to change issue status through a workflow UI
- As a user, I want to see the activity timeline to understand issue history

## Key Screens

### 1. Issue List View
**Header**
- Page title with issue count
- Sync button to trigger Gitea sync
- Create new issue button

**Search and Filters**
- Full-text search input
- Quick status filter dropdown
- Expandable filter panel with:
  - Priority filter
  - Sprint filter
  - Assignee filter
  - Labels filter
- Clear filters button

**Bulk Actions Bar** (appears when issues selected)
- Selection count
- Change Status button
- Assign button
- Add Labels button
- Delete button

**Issue Table**
- Checkbox column for selection
- Issue number (sortable)
- Title with label badges
- Status with icon
- Priority badge (sortable)
- Assignee with agent/user indicator
- Sprint badge or "Backlog"
- Sync status indicator
- Actions menu

### 2. Issue Detail View
**Header**
- Back button
- Issue number
- Status and priority badges
- Sync status
- Title
- Metadata (created, updated dates)
- External link to Gitea
- Edit and workflow action buttons

**Main Content (2/3)**
- Description card with markdown content
- Activity timeline with:
  - Status changes
  - Comments
  - Assignment changes
  - Label changes
  - Creation event
  - Agent/user avatars

**Sidebar (1/3)**
- Status workflow panel (clickable status list)
- Details panel:
  - Assignee with avatar
  - Reporter
  - Sprint
  - Story points
  - Due date
  - Labels
- Development panel:
  - Branch name
  - Pull request link

## User Flow

### Finding and Filtering Issues
1. User lands on issue list
2. User types in search box to filter
3. User selects status from dropdown
4. User expands filter panel for more options
5. User clears filters to reset

### Bulk Operations
1. User selects multiple issues via checkboxes
2. Bulk action bar appears
3. User clicks action (e.g., "Change Status")
4. Modal appears for status selection
5. Action applied to all selected issues

### Viewing and Updating Issue
1. User clicks issue row
2. Detail view shows full issue
3. User reviews description and activity
4. User clicks status in sidebar to change
5. Or clicks workflow button in header
6. Status updates and syncs to Gitea

## Design Decisions

### Table vs Card Layout
- Table chosen for density and scannability
- Columns prioritize most important info
- Sortable columns for user control
- Compact row height with key data visible

### Status Workflow
- Visual status list in sidebar
- Current status highlighted
- Click any status to change
- Workflow button in header for common transitions
- Matches Gitea/common issue tracker patterns

### Sync Status Indicator
- Small icon per issue showing sync state
- Synced (green check)
- Syncing (yellow spinner)
- Error (red alert)
- Critical for understanding data freshness

### Markdown Description
- Full markdown support planned
- Currently shows pre-formatted text
- Checkboxes for acceptance criteria
- Code blocks for technical details

### Activity Timeline
- Chronological (newest first option available)
- Avatar indicates agent vs human
- Grouped by type (status, comment, etc.)
- Vertical line connects events

## States

### Loading
- Skeleton rows in table
- Loading spinner in header

### Empty
- No issues: "Create your first issue" CTA
- No matches: "No issues found" with filter reset

### Error
- Failed to load: Error card with retry
- Sync error: Warning banner with retry

### Selected
- Row highlight on hover
- Checkbox checked state
- Bulk action bar visible

## Responsive Breakpoints

### Desktop (lg: 1024px+)
- Full table with all columns
- 2/3 + 1/3 split in detail view
- Extended filter panel inline

### Tablet (md: 768px)
- Table with key columns only
- Stacked detail view
- Collapsible filter panel

### Mobile (< 768px)
- Card-based list instead of table
- Single column detail view
- Bottom sheet for filters
- Touch-friendly checkboxes

## Accessibility Notes
- Table has proper header associations
- Checkbox has aria-label
- Status icons have text labels
- Sort direction announced
- Focus management on view changes
- Keyboard navigation for table rows

## Components Used
- Card, CardHeader, CardTitle, CardContent
- Button (default, outline, ghost variants)
- Badge (default, secondary, outline variants)
- Input (search)
- Select, SelectContent, SelectItem
- Checkbox
- Table, TableHeader, TableBody, TableRow, TableHead, TableCell
- Separator
- Lucide icons

## Filter Fields Reference

| Filter | Type | Options |
|--------|------|---------|
| Status | Select | All, Open, In Progress, In Review, Blocked, Done |
| Priority | Select | All, High, Medium, Low |
| Sprint | Select | All, Current sprints, Backlog |
| Assignee | Select | All, Unassigned, Agent list |
| Labels | Multi-select | Available labels |

## Status Workflow

```
Open --> In Progress --> In Review --> Done
  |          |              |
  v          v              v
Blocked <-- Blocked <---- Blocked
```

## Questions for Review
1. Should the table support drag-and-drop for status changes (Kanban-style)?
2. Is the sync status indicator clear enough?
3. Should we add inline editing for priority and assignee?
4. Should the activity timeline be collapsible for long histories?
5. Should we add keyboard shortcuts for common actions?
6. Should we show more columns or keep it minimal?

## How to View
Navigate to: `/prototypes/issue-management`

Click through the views:
1. Start on list view with sample issues
2. Use search and filters
3. Select checkboxes to see bulk actions
4. Click a row to see detail view
5. Click status buttons to see workflow

## Next Steps
After approval:
1. Implement real-time sync with Gitea via MCP
2. Add markdown rendering for descriptions
3. Implement comment posting
4. Add keyboard shortcuts
5. Implement bulk action modals
6. Add pagination for large issue lists
7. Implement inline editing
8. Add Kanban view as alternative
