triage-workflow

This skill prevents 5 common errors and saves ~60% tokens by using subagents.

| Metric | Without Skill | With Skill |

|--------|--------------|------------|

| Setup Time | 30+ min | 5-10 min |

| Common Errors | 5+ | 0 |

| Token Usage | 50k+ | ~20k |

Known Issues This Skill Prevents

1. Forgetting to create Linear ticket before starting work
2. Branch names not matching ticket identifiers
3. Commits missing ticket prefix (e.g., ICE-1965:)
4. OpenSpec proposals not validated before implementation
5. Context pollution from long-running workflows

This skill guides you through a 7-step triage workflow:

1. Create Linear Ticket - Use linearis CLI
2. Create Git Branch - Named after ticket identifier
3. Create OpenSpec Proposal - /openspec:proposal
4. User Validates Proposal - Review tasks and spec
5. Apply OpenSpec Changes - /openspec:apply
6. Commit Changes - /git-commit with ticket prefix
7. Push & Create PR - Optional, user decides

Step 1: Create Linear Ticket

```bash

# Run the helper script to create ticket

uv run scripts/create_linear_ticket.py "Issue title" --team TeamName --description "Details"

```

Why this matters: The ticket identifier (e.g., ICE-1965) becomes the prefix for branch names and commits.

Step 2: Create Branch from Ticket

```bash

# Use the helper script (gets GitHub username automatically)

uv run scripts/create_branch.py ICE-1965 --push

# Creates: nodnarbnitram/ICE-1965

```

Why this matters: Branch format username/identifier enables traceability and ownership clarity.

Step 3: Create OpenSpec Proposal

Use the slash command:

```

/openspec:proposal Add two-factor authentication

```

Why this matters: OpenSpec ensures alignment on requirements before implementation.

✅ Always Do

• ✅ Create Linear ticket FIRST before any code changes
• ✅ Use ticket identifier as branch name prefix
• ✅ Validate OpenSpec proposal with user before /openspec:apply
• ✅ Prefix all commits with ticket number (e.g., ICE-1965: Fix bug)
• ✅ Use subagents to keep main context clean

❌ Never Do

• ❌ Start coding without a Linear ticket
• ❌ Apply OpenSpec changes without user validation
• ❌ Commit without ticket prefix
• ❌ Push to main/master directly
• ❌ Skip the proposal validation step

Common Mistakes

❌ Wrong:

```bash

git commit -m "Fix authentication bug"

```

✅ Correct:

```bash

git commit -m "ICE-1965: Fix authentication bug"

```

Why: SOC II compliance requires ticket traceability in all commits.

| Issue | Root Cause | Solution |

|-------|-----------|----------|

| Missing ticket prefix | Forgot to extract identifier | Use /git-commit with prefix instruction |

| Branch name mismatch | Manual typing error | Use script to create branch from ticket |

| Proposal not validated | Rushed workflow | Always pause for user confirmation |

| Context bloat | Long workflows | Delegate to subagents for each step |

Phase 1: Ticket Creation

Use subagent to create Linear ticket:

```

> Create a Linear ticket for: [issue description]

```

The subagent will:

1. Run linearis issues create with appropriate parameters
2. Extract the ticket identifier from JSON response
3. Return the identifier (e.g., ICE-1965)

Linearis command reference:

```bash

linearis issues create "Title" \

--team Backend \

--description "Issue description" \

--priority 2 \

--labels "Bug,SOC-II"

```

Phase 2: Branch Creation

After getting ticket identifier:

```bash

# Use helper script to create branch with GitHub username

uv run scripts/create_branch.py ICE-1965 --push

# Creates: nodnarbnitram/ICE-1965

```

Phase 3: OpenSpec Proposal

Invoke the slash command:

```

/openspec:proposal [description of change]

```

This will:

1. Scaffold openspec/changes/[change-id]/
2. Create proposal.md, tasks.md, and delta specs
3. Return for user review

CRITICAL: Wait for user validation before proceeding!

Phase 4: User Validation

Present the proposal to user and ask:

• Do the tasks in tasks.md make sense?
• Is the scope in proposal.md correct?
• Are the delta specs accurate?

Only proceed when user confirms.

Phase 5: Apply OpenSpec Changes

After user validation:

```

/openspec:apply [change-name]

```

This implements the tasks defined in the proposal.

Phase 6: Commit Changes

Use the git-commit command with ticket prefix:

```

/git-commit ICE-1965:

```

The commit helper will:

1. Analyze staged changes
2. Generate commit message
3. Prefix with ticket number

Phase 7: Push & PR (Optional)

Ask user if they want to:

1. Push the branch
2. Create a pull request

If yes:

```bash

# Push

git push

# Create PR

gh pr create \

--title "ICE-1965: [Description]" \

--body "Fixes ICE-1965

• [Change description]

• [ ] Tests pass
• [ ] Manual verification"

```

Scripts

Located in scripts/:

• create_linear_ticket.py - Creates Linear ticket and returns identifier
• create_branch.py - Creates branch from ticket identifier
• create_pr.py - Creates PR with ticket reference

References

Located in references/:

• [linearis-reference.md](references/linearis-reference.md) - Linearis CLI commands
• [gh-cli-reference.md](references/gh-cli-reference.md) - GitHub CLI commands
• [openspec-reference.md](references/openspec-reference.md) - OpenSpec workflow

> Note: For deep dives on specific tools, see the reference files above.

Required

| Package | Version | Purpose |

|---------|---------|---------|

| linearis | latest | Linear ticket management |

| gh | 2.x+ | GitHub CLI for PRs |

| openspec | 2.x+ | Spec-driven development |

Optional

| Package | Version | Purpose |

|---------|---------|---------|

| jq | 1.6+ | JSON parsing for scripts |

• [Linearis GitHub](https://github.com/czottmann/linearis)
• [OpenSpec GitHub](https://github.com/Fission-AI/OpenSpec/)
• [GitHub CLI Manual](https://cli.github.com/manual/)

Linear ticket creation fails

Symptoms: linearis command returns error or empty response

Solution:

```bash

# Check authentication

echo $LINEAR_API_TOKEN

# Or check token file

cat ~/.linear_api_token

# Test with simple command

linearis issues list -l 1

```

OpenSpec proposal not found

Symptoms: /openspec:apply can't find the change

Solution:

```bash

# List active changes

openspec list

# Validate the change

openspec validate [change-id]

```

PR creation fails

Symptoms: gh pr create returns authentication error

Solution:

```bash

# Check GitHub auth

gh auth status

# Re-authenticate if needed

gh auth login

```

Before using this skill, verify:

• [ ] linearis CLI installed and authenticated (~/.linear_api_token exists)
• [ ] gh CLI installed and authenticated (gh auth status)
• [ ] openspec installed (npm install -g @fission-ai/openspec)
• [ ] Git configured with user name and email
• [ ] Team name known for Linear tickets