project-field-management

What this skill does

# GitHub Projects Field Management

This skill provides deep knowledge of GitHub Projects V2 custom fields, their types, capabilities, limitations, and best practices.

## Field Types Overview

### Single Select

**Purpose**: Dropdown with one choice from predefined options

**Use cases**:
- Status (Backlog, Todo, In Progress, Done)
- Priority (P0, P1, P2, P3)
- Component (Frontend, Backend, DevOps)
- Team (Team A, Team B, Team C)
- Environment (Dev, Staging, Prod)

**Characteristics**:
- Mutually exclusive choices
- Enables grouping in board views
- Filterable and searchable
- Color-coded options possible (via UI)
- Maximum ~50 options recommended

**CLI Creation**:
```bash
# IMPORTANT: Status field is built-in and already exists in new projects!
# Do NOT create a Status field - it's already there.

# For other SINGLE_SELECT fields, options are REQUIRED at creation:
gh project field-create <project-id> --owner "@me" \
  --data-type SINGLE_SELECT \
  --name "Priority" \
  --single-select-options "P0 (Critical),P1 (High),P2 (Medium),P3 (Low)"
```

**CRITICAL**:
- Options MUST be provided at creation time using `--single-select-options`
- Options cannot be added later via CLI
- Format: Comma-separated, no spaces after commas
- Status field is a built-in default field - never create it

**Best Practices**:
- Keep options list short (5-10 ideal)
- Use clear, unambiguous names
- Order logically (workflow progression)
- Avoid overlapping meanings
- Document what each option means

### Number

**Purpose**: Numeric values (integer or decimal)

**Use cases**:
- Story Points (1, 2, 3, 5, 8, 13)
- Estimated Hours (decimal)
- Customer Impact (count)
- Revenue Impact (dollars)
- Affected Users (count)
- Sprint Capacity (points)

**Characteristics**:
- Sortable and filterable
- Supports math operations (sum, average)
- No min/max validation (set via workflow norms)
- Can be decimal or integer

**CLI Creation**:
```bash
gh project field-create <project-id> --owner "@me" \
  --data-type NUMBER --name "Story Points"
```

**CLI Update**:
```bash
gh project item-edit --id <item-id> --project-id <project-id> \
  --field-id <field-id> --number 5
```

**Best Practices**:
- Document units (hours, points, count)
- Use consistent scale (Fibonacci for story points)
- Don't use for categorical data (use Single Select)
- Consider aggregation needs

### Date

**Purpose**: Calendar date (no time component)

**Use cases**:
- Due Date
- Start Date
- Launch Date
- Reported Date
- Target Completion
- Review By Date

**Characteristics**:
- Format: YYYY-MM-DD
- Enables timeline/roadmap views
- Sortable and filterable
- No time component (dates only)
- Past dates highlighted in red (in UI)

**CLI Creation**:
```bash
gh project field-create <project-id> --owner "@me" \
  --data-type DATE --name "Due Date"
```

**CLI Update**:
```bash
gh project item-edit --id <item-id> --project-id <project-id> \
  --field-id <field-id> --date "2025-12-31"
```

**Best Practices**:
- Use for deadlines and milestones
- Combine with Status for at-risk detection
- Set realistic dates (avoid always late pattern)
- Review and adjust dates as needed
- Use roadmap view for visualization

### Iteration

**Purpose**: Time-boxed planning cycles (sprints)

**Use cases**:
- 2-week sprints
- Monthly cycles
- Quarterly planning
- Release trains
- PI (Program Increment) planning

**Characteristics**:
- Fixed duration (1-4 weeks typical)
- Start and end dates
- Automatically creates future iterations
- Enables velocity tracking
- Burndown calculations
- Sortable chronologically

**CLI Creation**:
```bash
gh project field-create <project-id> --owner "@me" \
  --data-type ITERATION --name "Sprint"
```

**Configuration** (via UI):
- Set iteration duration (days)
- Set start date
- System generates future iterations

**CLI Update** (complex - requires iteration ID):
```bash
# First get iteration IDs via field-list
ITERATIONS=$(gh project field-list <project-id> --owner "@me" --format json | \
  jq '.[] | select(.name=="Sprint") | .configuration.iterations')

# Then update item with iteration ID
gh project item-edit --id <item-id> --project-id <project-id> \
  --field-id <field-id> --iteration-id <iteration-id>
```

**Best Practices**:
- Consistent duration (2 weeks standard)
- Start sprints on same weekday
- Name iterations clearly (Sprint 1, Sprint 2 or dates)
- Close/archive old iterations after 6 months
- Track velocity across iterations

### Text

**Purpose**: Free-form text input (single line)

**Use cases**:
- Owner name
- External ticket ID
- Slack thread link
- Sprint goal
- Related feature
- Customer name

**Characteristics**:
- Single line (not multiline)
- Searchable
- Not structured (no validation)
- Filterable (exact match or contains)
- Max length ~1000 characters

**CLI Creation**:
```bash
gh project field-create <project-id> --owner "@me" \
  --data-type TEXT --name "Owner"
```

**CLI Update**:
```bash
gh project item-edit --id <item-id> --project-id <project-id> \
  --field-id <field-id> --text "Alice Johnson"
```

**Best Practices**:
- Use for unstructured data only
- Consider Single Select if options are limited
- Document expected format (if any)
- Avoid using for categorical data
- Good for links and external references

## Built-in Fields

These fields exist automatically and cannot be customized:

### Title
- Item title
- Always visible
- Editable in place
- Searchable
- Required field

### Assignees
- GitHub user assignments
- Multiple assignees possible
- Inherited from issue/PR
- Can filter by assignee
- Enables workload distribution

### Labels
- Inherited from linked issue/PR
- Not directly editable in project
- Change on issue to reflect in project
- Filterable and searchable
- Color-coded

### Repository
- Where issue/PR resides
- Read-only in project
- Useful for multi-repo projects
- Filter by repo

### Milestone
- Inherited from issue/PR
- Not editable in project view
- Useful for release planning
- Can filter by milestone

### Linked Pull Requests
- PRs linked to issue
- Shows PR status
- Quick navigation
- Enables PR → Issue status sync

## Field Management Strategies

### Minimal Field Set

**Philosophy**: Only add fields you'll actively use

**Recommended minimum**:
- Status (required)
- Priority (required)
- One size/effort field (optional but recommended)

**When to use**:
- Small teams (<5 people)
- Simple projects
- Getting started with GitHub Projects
- Single-team projects

**Benefits**:
- Easy to maintain
- Low cognitive overhead
- Fast to use
- Less data entry

### Standard Field Set

**Philosophy**: Cover common planning needs

**Recommended fields**:
- Status
- Priority
- Story Points or Size
- Iteration or Sprint
- Component or Area
- Assignee (built-in)

**When to use**:
- Medium teams (5-20 people)
- Agile workflows
- Cross-functional teams
- Regular sprint planning

**Benefits**:
- Good balance of detail and simplicity
- Enables velocity tracking
- Supports sprint planning
- Reasonable overhead

### Comprehensive Field Set

**Philosophy**: Detailed tracking for complex projects

**Recommended fields**:
- Status
- Priority
- Story Points
- Sprint/Iteration
- Component
- Team
- Effort (hours)
- Customer Impact
- Due Date
- Owner
- External Ticket ID

**When to use**:
- Large organizations (>20 people)
- Multiple teams
- Regulatory requirements
- Executive reporting needs
- Complex dependencies

**Benefits**:
- Rich reporting capabilities
- Detailed tracking
- Multi-team coordination
- Audit trail

**Drawbacks**:
- High maintenance overhead
- More data entry required
- Can slow down workflow
- Risk of analysis paralysis

## Field Discovery & Querying

### Get All Fields for a Project

```bash
# List all fields with metadata
gh project field-list <project-number> --owner "@me" --format json

# Parse field names and types
gh project field-list <project-number> --owner "@me" --format json | \
  jq '.[] | {name: .name, type: .dataType, id: .id}'
```

### Get Field ID by Name

``