issues-workflow

What this skill does

# GitHub Issues-First Workflow

**Default**: Use GitHub Issues exclusively for all content, hierarchy, and tracking.
**Optional**: Link to Projects v2 for cross-repo visualization only.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## Critical Principle: Issues Are Everything

**GitHub Issues = Content + Hierarchy + Status + History.**
**GitHub Projects v2 = Visualization layer only (no content, no history).**

With sub-issues (GA April 2025), Issues now handle hierarchy natively. Projects v2 is reduced to an optional visualization dashboard.

### Issues vs Projects v2

| Capability       | Issues (Default)             | Projects v2 (Visualization Only)   |
| ---------------- | ---------------------------- | ---------------------------------- |
| **Content**      | Body, comments, code blocks  | None (links to Issues only)        |
| **Hierarchy**    | Sub-issues (100 per parent)  | Flat list                          |
| **Status**       | Open/Closed + labels         | Custom fields (no history)         |
| **Edit history** | Full diff on every edit      | None                               |
| **Timeline**     | All changes logged           | Status changes only (30-day limit) |
| **Search**       | Full-text + 30+ filters      | Limited                            |
| **CLI**          | `gh issue list/view/create`  | `gh project` (Classic PAT only)    |
| **Cross-repo**   | Manual (`--repo A --repo B`) | Single dashboard view              |

### When to Use Each

```
┌─────────────────────────────────────────────────────────────┐
│                 ISSUES-FIRST WORKFLOW                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   ALWAYS use Issues for:                                     │
│   ├── All content (findings, analysis, conclusions)          │
│   ├── Hierarchy (parent + sub-issues)                        │
│   ├── Status tracking (labels: status:in-progress)           │
│   ├── Categorization (labels: research:regime, priority:P0)  │
│   └── Filtering (gh issue list --label X --state Y)          │
│                                                              │
│   OPTIONALLY use Projects v2 for:                            │
│   ├── Cross-repo dashboard (single view across repos)        │
│   ├── Kanban visualization (drag-and-drop board)             │
│   ├── Roadmap timeline (visual date-based view)              │
│   └── Stakeholder reporting (Status Updates feed)            │
│                                                              │
│   NEVER put in Projects v2:                                  │
│   ├── Research findings (no edit history)                    │
│   ├── Analysis details (lost on update)                      │
│   ├── Any text content (use Issue body/comments)             │
│   └── Anything you need to track changes for                 │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### Decision Tree

```
Need to track work?
├── Single repo, <50 issues → Issues only (skip Projects)
├── Single repo, 50+ issues → Issues + optional Project for kanban
├── Multiple repos → Issues + Project for cross-repo dashboard
└── Stakeholder visibility → Issues + Project Status Updates
```

## When to Use This Skill

Use this skill when:

- Setting up issue hierarchy with sub-issues (default workflow)
- Creating cross-repo visualization dashboards
- Configuring auto-linking from Issues to Projects
- Setting up stakeholder Status Updates

**Remember**: All content lives in Issues. Projects v2 is a read-only visualization layer.

## Invocation

**Slash command**: `/gh-tools:issues-workflow`

**Natural language triggers**:

- "Create sub-issues for this parent"
- "Set up issue hierarchy"
- "Create cross-repo dashboard"
- "Link issues to project for visualization"

## Issues-First Workflow (Default)

### Sub-Issues: Native Hierarchy (GA April 2025)

Sub-issues replace the need for Projects v2 hierarchy. Use for all structured work.

#### When to Use Sub-Issues

| Use Case                     | Example                                                             | Why Sub-Issues                             |
| ---------------------------- | ------------------------------------------------------------------- | ------------------------------------------ |
| **Research breakdown**       | Parent: "Investigate microstructure" → Subs: individual patterns    | Track which patterns validated/invalidated |
| **Epic decomposition**       | Parent: "User authentication" → Subs: login, logout, password reset | Progress bar shows completion %            |
| **Multi-step investigation** | Parent: "Debug performance issue" → Subs: profiling, memory, CPU    | Each sub can be assigned differently       |
| **Phased work**              | Parent: "v2.0 release" → Subs: Phase 1, Phase 2, Phase 3            | Natural ordering with timeline             |

#### When NOT to Use Sub-Issues

| Situation                    | Use Instead                           | Why                            |
| ---------------------------- | ------------------------------------- | ------------------------------ |
| Simple checklist (< 5 items) | Markdown checkboxes in issue body     | Less overhead, editable inline |
| Cross-repo dependencies      | Issue references (`See org/repo#123`) | Sub-issues are same-repo only  |
| Loose relationships          | "Related to #X" in body               | Sub-issues imply containment   |
| One-off tasks                | Single issue with labels              | Don't over-structure           |

#### Creating Sub-Issues

```bash
# Create parent issue
gh issue create --title "Research: Range Bar Microstructure" \
  --label "research:parent" --repo terrylica/rangebar-py

# Create sub-issues (reference parent in body or use UI)
gh issue create --title "Regime detection patterns" \
  --body "Parent: #100" --label "research:sub" --repo terrylica/rangebar-py
```

**Structure example**:

```
#100 Research: Range Bar Microstructure (parent)
├── #101 Regime detection patterns - Invalidated ✗
├── #102 Cross-threshold correlations - Validated ✓
├── #103 Duration normalization - In Progress
└── #104 Microstructure features v7.0 - Open
```

#### Sub-Issue Features

- **Progress bar**: Parent shows "X of Y completed" with visual bar
- **Bidirectional links**: Sub shows "Parent issue" in sidebar, parent lists all subs
- **Automatic tracking**: Close sub → parent progress updates
- **Nesting**: Up to 8 levels deep (sub-sub-sub-issues)
- **Limit**: 100 sub-issues per parent

**Migration Note**: Tasklist blocks retired April 30, 2025. Sub-issues are the official replacement. No migration tooling - manual conversion required.

### Status via Labels (No Projects Needed)

Use labels instead of Project custom fields:

| Label Pattern | Purpose                 | Example              |
| ------------- | ----------------------- | -------------------- |
| `status:*`    | Workflow state          | `status:in-progress` |
| `priority:*`  | Urgency                 | `priority:P0`        |
| `research:*`  | Research categorization | `research:validated` |
| `type:*`      | Issue classification    | `type:hypothesis`    |

```bash
# Filter by status
gh issue list --label "status:in-progress" --repo terrylica/rangebar-py

# Filter by research outcome
gh issue list --label "research:validated" --state all

# Combined filters
gh issue list --label "research:regime,status:complete" --state closed
```

### Issue Types (GA 2025)

Organization-level standardization (orgs only, not personal accounts):

```bash
# Configure at: Organization Settings → Issues → Issue Types
# Personal accounts: Use labels instead (type:hypothes