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/ < owner

/ < repo

/issues/ < 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 --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