SOC II Triage Workflow

Orchestrates the complete triage process: Linear ticket → branch → OpenSpec proposal → implementation → commit → PR

⚠️ BEFORE YOU START

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

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

Workflow Overview

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

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

Quick Start

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.

Critical Rules

✅ 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.

Known Issues Prevention

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

Detailed Workflow Steps

Phase 1: Ticket Creation

Use subagent to create Linear ticket:

> Create a Linear ticket for: [issue description]

The subagent will:

Run
```
linearis issues create
```
with appropriate parameters
Extract the ticket identifier from JSON response
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:

Scaffold
```
openspec/changes/[change-id]/
```
Create
```
proposal.md
```
,
```
tasks.md
```
, and delta specs
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:

Analyze staged changes
Generate commit message
Prefix with ticket number

Phase 7: Push & PR (Optional)

Ask user if they want to:

Push the branch
Create a pull request

If yes:

bash

# Push
git push

# Create PR
gh pr create \
  --title "ICE-1965: [Description]" \
  --body "Fixes ICE-1965

## Summary
- [Change description]

## Test Plan
- [ ] Tests pass
- [ ] Manual verification"

Bundled Resources

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
```
- Linearis CLI commands
```
gh-cli-reference.md
```
- GitHub CLI commands
```
openspec-reference.md
```
- OpenSpec workflow

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

Dependencies

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

Official Documentation

Troubleshooting

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

Setup Checklist

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

triage-workflow

NPX Install

Tags

SKILL.md Content

SOC II Triage Workflow

⚠️ BEFORE YOU START

Known Issues This Skill Prevents

Workflow Overview

Quick Start

Step 1: Create Linear Ticket

Step 2: Create Branch from Ticket

Step 3: Create OpenSpec Proposal

Critical Rules

✅ Always Do

❌ Never Do

Common Mistakes

Known Issues Prevention

Detailed Workflow Steps

Phase 1: Ticket Creation

Phase 2: Branch Creation

Phase 3: OpenSpec Proposal

Phase 4: User Validation

Phase 5: Apply OpenSpec Changes

Phase 6: Commit Changes

Phase 7: Push & PR (Optional)

Bundled Resources

Scripts

References

Dependencies

Required

Optional

Official Documentation

Troubleshooting

Linear ticket creation fails

OpenSpec proposal not found

PR creation fails

Setup Checklist