triage-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SOC II Triage Workflow

SOC II 分类工作流

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

统筹完整的分类流程：Linear工单 → 分支 → OpenSpec提案 → 实现开发 → 提交记录 → 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

本技能通过使用子代理可预防5类常见错误，并节省约60%的令牌消耗。

指标	未使用该技能	使用该技能
设置时间	30+ 分钟	5-10 分钟
常见错误数量	5+	0
令牌使用量	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

开始工作前忘记创建Linear工单
分支名称与工单标识符不匹配
提交记录缺少工单前缀（例如：
```
ICE-1965:
```
）
OpenSpec提案未经验证就开始实现
长时运行工作流导致的上下文污染

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

本技能将引导你完成7步分类工作流：

创建Linear工单 - 使用
```
linearis
```
CLI
创建Git分支 - 以工单标识符命名
创建OpenSpec提案 - 执行
```
/openspec:proposal
```
用户验证提案 - 审核任务与规范
应用OpenSpec变更 - 执行
```
/openspec:apply
```
提交变更 - 使用
```
/git-commit
```
并添加工单前缀
推送并创建PR - 可选操作，由用户决定

Quick Start

快速开始

Step 1: Create Linear Ticket

步骤1：创建Linear工单

bash

undefined

bash

undefined

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.

uv run scripts/create_linear_ticket.py "问题标题" --team 团队名称 --description "详细信息"


**重要性说明：** 工单标识符（例如：`ICE-1965`）将作为分支名称和提交记录的前缀。

Step 2: Create Branch from Ticket

步骤2：基于工单创建分支

bash

undefined

bash

undefined

Use the helper script (gets GitHub username automatically)

使用辅助脚本（自动获取GitHub用户名）

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

Creates: nodnarbnitram/ICE-1965

创建的分支格式：nodnarbnitram/ICE-1965


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


**重要性说明：** `用户名/标识符` 的分支格式可实现可追溯性与职责清晰化。

Step 3: Create OpenSpec Proposal

步骤3：创建OpenSpec提案

Use the slash command:

/openspec:proposal Add two-factor authentication

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

使用斜杠命令：

/openspec:proposal 添加双因素认证

重要性说明： OpenSpec可确保在实现前就需求达成一致。

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

✅ 先创建Linear工单，再进行任何代码变更
✅ 使用工单标识符作为分支名称前缀
✅ 在执行
```
/openspec:apply
```
前，必须由用户验证OpenSpec提案
✅ 所有提交记录都要添加工单号前缀（例如：
```
ICE-1965: 修复Bug
```
）
✅ 使用子代理保持主上下文整洁

❌ 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

❌ 未创建Linear工单就开始编码
❌ 未经过用户验证就应用OpenSpec变更
❌ 提交记录不添加工单前缀
❌ 直接推送到main/master分支
❌ 跳过提案验证步骤

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.

❌ 错误写法：

bash

git commit -m "修复认证Bug"

✅ 正确写法：

bash

git commit -m "ICE-1965: 修复认证Bug"

原因： SOC II合规要求所有提交记录都需关联可追溯的工单。

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

问题	根本原因	解决方案
提交记录缺少工单前缀	忘记提取工单标识符	使用 `/git-commit` 并附带前缀指令
分支名称不匹配	手动输入错误	使用脚本基于工单创建分支
提案未验证	工作流过于仓促	必须暂停等待用户确认
上下文冗余	长时运行工作流	将各步骤委托给子代理处理

Detailed Workflow Steps

详细工作流步骤

Phase 1: Ticket Creation

阶段1：工单创建

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"

使用子代理创建Linear工单：

> 为以下内容创建Linear工单：[问题描述]

子代理将执行：

使用合适参数运行
```
linearis issues create
```
从JSON响应中提取工单标识符
返回标识符（例如：
```
ICE-1965
```
）

Linearis命令参考：

bash

linearis issues create "标题" \
  --team 后端团队 \
  --description "问题描述" \
  --priority 2 \
  --labels "Bug,SOC-II"

Phase 2: Branch Creation

阶段2：分支创建

After getting ticket identifier:

bash

undefined

获取工单标识符后执行：

bash

undefined

Use helper script to create branch with GitHub username

使用辅助脚本结合GitHub用户名创建分支

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

Creates: nodnarbnitram/ICE-1965

创建的分支：nodnarbnitram/ICE-1965

undefined

undefined

Phase 3: OpenSpec Proposal

阶段3：OpenSpec提案

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!

调用斜杠命令：

/openspec:proposal [变更描述]

该命令将：

生成
```
openspec/changes/[变更ID]/
```
目录结构
创建
```
proposal.md
```
、
```
tasks.md
```
和增量规范文件
提交给用户审核

核心要求： 必须等待用户验证后再继续！

Phase 4: User Validation

阶段4：用户验证

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.

向用户展示提案并确认：

```
tasks.md
```
中的任务是否合理？
```
proposal.md
```
中的范围是否准确？
增量规范是否无误？

仅在用户确认后才可继续。

Phase 5: Apply OpenSpec Changes

阶段5：应用OpenSpec变更

After user validation:

/openspec:apply [change-name]

This implements the tasks defined in the proposal.

用户验证通过后执行：

/openspec:apply [变更名称]

该命令将实现提案中定义的所有任务。

Phase 6: Commit Changes

阶段6：提交变更

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

使用带工单前缀的git-commit命令：

/git-commit ICE-1965:

提交辅助工具将：

分析暂存的变更内容
生成提交信息
添加工单号前缀

Phase 7: Push & PR (Optional)

阶段7：推送并创建PR（可选）

Ask user if they want to:

Push the branch
Create a pull request

If yes:

bash

undefined

询问用户是否需要：

推送分支
创建拉取请求（PR）

若用户确认，执行：

bash

undefined

Push

推送分支

git push

Create PR

创建PR

gh pr create
--title "ICE-1965: [Description]"
--body "Fixes ICE-1965

gh pr create
--title "ICE-1965: [描述内容]"
--body "修复ICE-1965

Summary

变更摘要

[Change description]

[变更描述]

Test Plan

测试计划

Tests pass
Manual verification"

undefined

测试通过
手动验证完成"

undefined

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

位于

scripts/

目录下：

```
create_linear_ticket.py
```
- 创建Linear工单并返回标识符
```
create_branch.py
```
- 基于工单标识符创建分支
```
create_pr.py
```
- 创建关联工单的PR

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.

位于

references/

目录下：

```
linearis-reference.md
```
- Linearis CLI命令参考
```
gh-cli-reference.md
```
- GitHub CLI命令参考
```
openspec-reference.md
```
- OpenSpec工作流参考

注意： 如需深入了解特定工具，请查看上述参考文件。

Dependencies

依赖项

Required

必需依赖

Package	Version	Purpose
linearis	latest	Linear ticket management
gh	2.x+	GitHub CLI for PRs
openspec	2.x+	Spec-driven development

包名	版本	用途
linearis	latest	Linear工单管理
gh	2.x+	用于PR操作的GitHub CLI
openspec	2.x+	规范驱动开发

Optional

可选依赖

Package	Version	Purpose
jq	1.6+	JSON parsing for scripts

包名	版本	用途
jq	1.6+	脚本中的JSON解析

Official Documentation

官方文档

Troubleshooting

故障排查

Linear ticket creation fails

Linear工单创建失败

Symptoms:

linearis

command returns error or empty response

Solution:

bash

undefined

症状：

linearis

命令返回错误或空响应

解决方案：

bash

undefined

Check authentication

检查认证状态

echo $LINEAR_API_TOKEN

Or check token file

或检查令牌文件

cat ~/.linear_api_token

Test with simple command

使用简单命令测试

linearis issues list -l 1

undefined

linearis issues list -l 1

undefined

OpenSpec proposal not found

OpenSpec提案无法找到

Symptoms:

/openspec:apply

can't find the change

Solution:

bash

undefined

症状：

/openspec:apply

无法找到指定变更

解决方案：

bash

undefined

List active changes

列出所有活跃变更

openspec list

Validate the change

验证变更有效性

openspec validate [change-id]

undefined

openspec validate [变更ID]

undefined

PR creation fails

PR创建失败

Symptoms:

gh pr create

returns authentication error

Solution:

bash

undefined

症状：

gh pr create

返回认证错误

解决方案：

bash

undefined

Check GitHub auth

检查GitHub认证状态

gh auth status

Re-authenticate if needed

如需重新认证

gh auth login

undefined

gh auth login

undefined

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

使用本技能前，请确认以下项已完成：

```
linearis
```
CLI已安装并完成认证（
```
~/.linear_api_token
```
文件存在）
```
gh
```
CLI已安装并完成认证（执行
```
gh auth status
```
验证）

openspec

已安装（执行

npm install -g @fission-ai/openspec

）

Git已配置用户名和邮箱
已知Linear工单对应的团队名称