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.

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

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

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):

Configure at: Organization Settings → Issues → Issue Types

Personal accounts: Use labels instead (type:hypothesis, type:finding)

Projects v2: Visualization Layer (Optional)

Use Projects v2 only for cross-repo visualization. All content remains in Issues.

When to Use Projects v2

Use Case Why Projects v2 Helps

Cross-repo dashboard Single view across multiple repos

Kanban board Drag-and-drop visual workflow

Roadmap timeline Date-based visual planning

Stakeholder Status Status Updates feed (ON_TRACK, etc.)

When NOT to Use Projects v2

• Single repo with < 50 issues (use gh issue list filters)

• Need edit history (Projects has none)

• Need content storage (use Issue body/comments)

• Need version tracking (Projects loses previous values)

Auto-Linking Issues to Projects

Link Issues automatically so Projects stay in sync:

Option 1: Label prefix convention

Label Auto-links to

project:research

Research Findings

project:dev

Active Development

Option 2: Config file (.github/project-links.json ):

{ "mappings": [ { "labels": ["research:regime", "research:validated"], "projectNumber": 2 } ], "owner": "terrylica" }

Status Updates (Stakeholder Communication)

Create status update via GraphQL

gh api graphql -f query=' mutation($projectId: ID!, $body: String!, $status: ProjectV2StatusUpdateStatus!) { createProjectV2StatusUpdate(input: { projectId: $projectId body: $body startDate: "2026-02-01" status: $status }) { statusUpdate { id status body } } }' -f projectId="PVT_xxx" -f body="Research phase complete" -f status="ON_TRACK"

Status values: ON_TRACK | AT_RISK | OFF_TRACK | COMPLETE | INACTIVE

Token Requirements

CRITICAL: Projects v2 API requires Classic PAT with project scope.

Check token type

cat ~/.claude/.secrets/gh-token-terrylica | head -c 10

ghp_ = Classic PAT (supports Projects)

github_pat_ = Fine-grained (NO Projects support)

Project Commands Reference

List/create/view projects

gh project list --owner <owner> gh project create --owner <owner> --title "Dashboard Name" gh project view <number> --owner <owner>

Link issues to project (for visualization)

gh project item-add <project-number> --owner <owner>
--url https://github.com/&#x3C;owner>/&#x3C;repo>/issues/&#x3C;number>

Bulk link by label

gh issue list --repo terrylica/rangebar-py
--label "research:regime" --json url --jq '.[].url' |
while read url; do gh project item-add 2 --owner terrylica --url "$url" done

GitHub Issues: Complete Feature Reference

Core Issue Commands

Create issue

gh issue create --title "Title" --body "Body" --label "label1,label2"

Create with body file (alternative for very long content)

gh issue create --title "Title" --body-file /tmp/issue-body.md

View issue

gh issue view <number> --repo owner/repo

List with filters

gh issue list --label "research:validated" --state all --assignee @me

Edit issue

gh issue edit <number> --add-label "status:complete" --remove-label "status:in-progress"

Close/reopen

gh issue close <number> --reason completed gh issue reopen <number>

Advanced Filtering (30+ qualifiers)

By multiple labels (AND logic)

gh issue list --label "research:regime,priority:P0"

By milestone

gh issue list --milestone "Research Phase 1"

By date

gh issue list --search "created:>2025-01-01 updated:<2025-12-01"

By author/assignee

gh issue list --author @me --assignee username

Full-text search

gh issue list --search "microstructure in:title,body"

Combine everything

gh issue list
--label "research:validated"
--state closed
--search "regime created:>2025-06-01"
--json number,title,labels

Issue Relationships

Reference in body (creates link in timeline)

"Related to #45" "Closes #123" "Fixes #456"

Cross-repo reference

"See terrylica/other-repo#789"

Sub-issue (parent reference in body)

"Parent: #100"

Timeline and History

View full timeline (all events)

gh api repos/owner/repo/issues/123/timeline --paginate

View edit history (via web UI or API)

gh api repos/owner/repo/issues/123 --jq '.body_html'

Comment with preserved history

gh issue comment <number> --body "Update: new findings"

Milestones (Alternative to Project Iterations)

List milestones

gh api repos/owner/repo/milestones

Create milestone

gh api repos/owner/repo/milestones -f title="Research Phase 2" -f due_on="2026-03-01"

Assign issue to milestone

gh issue edit <number> --milestone "Research Phase 2"

Workflow Examples

Issues-Only Research Workflow

1. Create parent research issue

gh issue create
--title "Research: Range Bar Microstructure Patterns"
--label "research:parent,priority:P1"
--body-file /tmp/research-parent.md

2. Create sub-issues for each investigation

for topic in "regime-detection" "cross-threshold" "duration-normalization"; do gh issue create
--title "Sub: $topic analysis"
--label "research:sub"
--body "Parent: #100" done

3. Track progress via labels

gh issue edit 101 --add-label "research:invalidated" gh issue edit 102 --add-label "research:validated" gh issue close 101 --reason "not planned"

4. Filter to see status

gh issue list --label "research:sub" --state all --json number,title,state,labels

Optional: Add to Project for Visualization

Only if you need cross-repo dashboard

gh issue list --label "research:validated" --json url --jq '.[].url' |
while read url; do gh project item-add 2 --owner terrylica --url "$url" done

Title Evolution: Re-evaluate on New Comments

PRINCIPLE: GitHub issue titles have a 256-character limit. Maximize this limit to create informative titles that reflect the current state of the issue.

When to Re-evaluate

Re-evaluate and potentially update the issue title when significant new information is added - new findings, status changes, scope expansion, or when the journey is complete.

Commands

Check current title length

gh issue view <number> --json title --jq '.title | length'

Update title (maximize 256 chars based on content)

gh issue edit <number> --title "..."

The AI agent determines the best way to maximize informativeness based on the nature of the content.

Issue-Branch-PR Lifecycle

The full lifecycle from issue to merged code, with automatic issue closure. All automation is local — no GitHub Actions for testing/linting.

Recommended Workflow

1. Create issue(s) → gh issue create --title "..." --body "..."
2. Branch from issue → gh issue develop <N> --checkout
3. Implement + commit → git commit -m "feat: description"
4. Create PR (with keywords) → gh pr create --body "Closes #N"
5. Merge PR → gh pr merge --squash --delete-branch
6. Issue auto-closes → GitHub handles this automatically

Closing Keywords (Auto-Close on Merge)

Use Closes #N , Fixes #N , or Resolves #N in PR body (not title) to auto-close issues on merge. Case-insensitive. Cross-repo: Closes owner/repo#N . Each issue needs its own keyword — Closes #1, closes #2, fixes #3 .

Branch-from-Issue (gh issue develop )

gh issue develop 214 --checkout # auto-names branch gh issue develop 214 --name feat/x --checkout # custom name

Creates branch linked to issue. PRs from this branch auto-link and auto-close the issue on merge.

Use both develop AND closing keywords — belt-and-suspenders.

Full reference: Issue-Branch Lifecycle Details — keyword placement rules, cross-repo closing, bulk closure, branch cleanup

GFM Rendering Anti-Patterns

NEVER use bare #N in issue/PR comments. GitHub auto-links any #N where issue N exists — in prose, tables, lists. This is unpredictable and inconsistent (some numbers link, others don't).

• To reference an issue: Use explicit full URL → Issue 13

• For non-issue numbers: Suppress with backtick → #1

• Backslash #1 does NOT work inside table cells

See the full reference for 6 documented anti-patterns: GFM Anti-Patterns Reference

Troubleshooting

Issue Cause Fix

#N auto-links in tables GFM auto-reference Use backtick code span: #1 (details)

"Resource not accessible" Fine-grained PAT Use Classic PAT for Projects v2

Sub-issues not linking Wrong body format Use exact "Parent: #123" syntax

Labels not filtering correctly Typo in label name gh label list to verify exact names

Long body truncated GitHub 65536-char API limit Shorten content or split across comments

Title too short/vague Not using full limit Maximize 256-char limit for context

References

• gh-tools Issue Create Skill

• Issue-Branch Lifecycle — Closing keywords, gh issue develop , local-first automation

• GFM Anti-Patterns

• Field Types Reference

• Auto-Link Configuration

• GraphQL Queries Reference

• GitHub Issues Documentation