scope-task

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scope Task

Overview

概述

This skill researches and scopes a single new task, then inserts it into an existing ROADMAP.md at the specified position. It follows the same discovery depth as project-init — web research, self-reflection, and user interview — but focused on one task rather than an entire project. The output is a properly formatted action item inserted into the roadmap, ready for

do-task

to implement.

该Skill会调研并梳理单个新任务，然后将其插入到现有ROADMAP.md的指定位置。它遵循与project-init相同的调研深度——包括网络调研、自我反思和用户访谈，但聚焦于单个任务而非整个项目。输出结果是插入到路线图中的格式规范的行动项，可直接通过

do-task

进行实施。

Workflow

工作流程

Step 1: Parse Arguments

步骤1：解析参数

Extract two pieces from the user's input:

Task ID — numeric identifier in
```
<phase>.<item>
```
format (e.g.,
```
2.5
```
,
```
3.3
```
)
Task Title — the descriptive title following the ID (e.g., "Integrate Research into SPEC.md")

If either is missing or malformed, ask the user to provide the full invocation:

/scope-task <phase.item> <Task Title>

从用户输入中提取两部分信息：

任务ID — 采用
```
<阶段>.<项>
```
格式的数字标识符（例如
```
2.5
```
、
```
3.3
```
）
任务标题 — 跟随在ID后的描述性标题（例如“将调研内容整合到SPEC.md”）

如果任一信息缺失或格式错误，请要求用户提供完整的调用指令：

/scope-task <phase.item> <任务标题>

。

Step 2: Load Project Context

步骤2：加载项目上下文

Read the following files from the current working directory (check

docs/

subdirectory first, then project root):

ROADMAP.md — to understand existing phases, task numbering, and what has already been scoped
SPEC.md — to understand the project's architecture, tech stack, data models, and key decisions

If ROADMAP.md does not exist, inform the user and stop — this skill requires an existing roadmap to insert into.

Validate the task ID:

The phase number must correspond to an existing phase in the roadmap (Phases 1-4 for actionable tasks; Phase 5 for future directions)
The item number must not already exist — scope-task always creates new insertions
If the ID conflicts with an existing task, list nearby IDs and ask the user to pick an available slot

从当前工作目录读取以下文件（优先检查

docs/

ROADMAP.md — 用于了解现有阶段、任务编号以及已梳理的内容
SPEC.md — 用于了解项目的架构、技术栈、数据模型和关键决策

如果ROADMAP.md不存在，请告知用户并终止操作——该Skill需要基于已有的路线图进行插入操作。

验证任务ID：

阶段编号必须与路线图中的现有阶段对应（阶段1-4为可执行任务；阶段5为未来规划方向）
项编号不能已存在——scope-task始终用于创建新的插入项
如果ID与现有任务冲突，请列出附近的ID并要求用户选择一个可用的编号

Step 3: Research

步骤3：调研

Conduct targeted research using

WebSearch

to investigate:

Best practices — established patterns and approaches for this type of task given the project's tech stack
Similar implementations — how other projects have solved this problem
Libraries and tools — relevant packages, APIs, or utilities that could aid implementation
Trade-offs — alternative approaches with their pros and cons
Pitfalls — common mistakes and gotchas specific to this task

Keep research focused on the single task — not the broader project. Use SPEC.md context to make searches specific to the project's stack and architecture.

使用

WebSearch

进行针对性调研，内容包括：

最佳实践 — 结合项目技术栈，该类任务的既定模式和实现方法
类似实现案例 — 其他项目如何解决该问题
库与工具 — 可辅助实现的相关包、API或实用工具
权衡方案 — 不同实现方案的优缺点
常见陷阱 — 该任务特有的常见错误和注意事项

调研需聚焦于单个任务，而非更广泛的项目。结合SPEC.md中的上下文信息，使调研更贴合项目的技术栈和架构。

Step 4: Self-Reflection

步骤4：自我反思

Before interviewing the user, pause and reason through:

How research findings connect to the project's existing architecture (from SPEC.md)
What the task's requirements should be, based on research
Gaps in understanding that only the user can fill
Potential impacts on other roadmap tasks
Scope boundaries — what this task should and should not include
Questions where the answer is NOT obvious from SPEC.md, ROADMAP.md, or research

在访谈用户之前，先暂停并梳理以下内容：

调研结果如何与项目现有架构（来自SPEC.md）相结合
基于调研结果，该任务应具备哪些需求
只有用户才能填补的认知缺口
对路线图中其他任务的潜在影响
范围边界——该任务应包含和不应包含的内容
答案无法从SPEC.md、ROADMAP.md或调研中直接得出的问题

Step 5: Interview

步骤5：用户访谈

Use

AskUserQuestion

to clarify unresolved items from Steps 2-4. Topics may include:

Technical implementation choices surfaced by research
Scope boundaries — what exactly should be in vs. out
Integration points with existing or planned roadmap tasks
Acceptance criteria the user has in mind
Priority or ordering relative to neighboring tasks

Rules for the interview:

Do NOT ask questions whose answers are obvious from SPEC.md, ROADMAP.md, or research
Do NOT re-ask information already present in the project documentation
Each round should surface genuinely new information
Keep it focused — this is one task, not a full project discovery
1-2 rounds of questions is typical; go deeper only if the task is genuinely complex

使用

AskUserQuestion

澄清步骤2-4中未解决的问题，话题可能包括：

调研中发现的技术实现选择
范围边界——具体应包含和排除的内容
与现有或规划中路线图任务的集成点
用户预期的验收标准
相对于相邻任务的优先级或排序

访谈规则：

不要询问答案可从SPEC.md、ROADMAP.md或调研中直接获得的问题
不要重复询问项目文档中已有的信息
每一轮访谈应获取真正的新信息
聚焦于单个任务，而非完整的项目调研
通常进行1-2轮访谈即可；仅当任务确实复杂时才需要更深入的沟通

Step 6: Write the Action Item

步骤6：撰写行动项

Compose the new task following the canonical roadmap format.

For Phases 1-4, use exactly 3 subsections:

markdown

undefined

按照标准路线图格式撰写新任务。

对于阶段1-4，严格使用以下3个小节：

markdown

undefined

<phase>.<item> <Task Title>

<phase>.<item> <任务标题>

Description: What this task is and why it matters. Connect it to the project's goals and architecture.

Requirements:

Concrete deliverable 1
Concrete deliverable 2
...

Implementation Notes: Technical guidance, references to specific libraries or APIs discovered during research, trade-offs considered, gotchas to watch for. Reference relevant parts of SPEC.md where helpful.


**For Phase 5 (Future)**, use the alternative format:

```markdown

描述：该任务的内容及其重要性。关联项目目标与架构。

需求:

具体交付物1
具体交付物2
...

实施说明：技术指导，包括调研中发现的特定库或API参考、考虑过的权衡方案、需要注意的陷阱。必要时可参考SPEC.md中的相关内容。


**对于阶段5（未来规划）**，使用替代格式：

```markdown

<phase>.<item> <Task Title>

<phase>.<item> <任务标题>

Description: What this direction is about.

Features:

Potential feature or capability 1
Potential feature or capability 2

Rationale: Why this direction is worth pursuing.


Quality guidelines for the action item:
- Requirements should be concrete, testable, and individually checkable
- Implementation Notes should contain genuinely useful technical guidance drawn from research — not generic advice
- Description should clearly explain *why* this task matters in the context of the project
- Target 4-10 requirement items depending on task complexity
- Reference specific libraries, APIs, or patterns by name when applicable

描述：该规划方向的内容。

特性:

潜在特性或功能1
潜在特性或功能2

理由：该规划方向值得推进的原因。


行动项质量规范：
- 需求应具体、可测试且可单独验证
- 实施说明应包含来自调研的实用技术指导，而非通用建议
- 描述应清晰说明该任务在项目背景下的重要性
- 根据任务复杂度，定义4-10项需求
- 适用时请明确引用具体的库、API或模式名称

Step 7: Insert into ROADMAP.md

步骤7：插入到ROADMAP.md

Insert the new action item into ROADMAP.md at the correct position:

Place it after the task with the preceding item number (e.g.,
```
2.5
```
goes after
```
2.4
```
)
If inserting at the end of a phase (e.g.,
```
2.5
```
when the last task is
```
2.4
```
), place it before the next phase heading
If inserting between existing tasks (e.g.,
```
2.5
```
between
```
2.4
```
and
```
2.6
```
), place it in numerical order
Do NOT renumber existing tasks — the new ID fills a gap or extends the sequence
Preserve all existing content and formatting in the roadmap

Use the

Edit

tool to insert the new task. Verify the insertion by reading back the modified section of ROADMAP.md.

将新行动项插入到ROADMAP.md的正确位置：

放置在具有前一项编号的任务之后（例如
```
2.5
```
放在
```
2.4
```
之后）
如果插入到阶段末尾（例如当前最后一项任务是
```
2.4
```
，插入
```
2.5
```
），请放置在下一个阶段标题之前
如果插入到现有任务之间（例如
```
2.5
```
放在
```
2.4
```
和
```
2.6
```
之间），请按数字顺序排列
不要重新编号现有任务——新ID用于填补缺口或扩展序列
保留路线图中的所有现有内容和格式

使用

Edit

工具插入新任务。通过读取ROADMAP.md中修改后的部分来验证插入结果。

Step 8: Summary

步骤8：总结

After insertion, present a brief summary to the user:

The task ID and title
A one-line description of what was scoped
The number of requirements defined
Any notable trade-offs or decisions made during scoping

The task is now ready for

/do-task <id>

插入完成后，向用户展示简要总结：

任务ID和标题
梳理内容的一句话描述
定义的需求数量
梳理过程中做出的重要权衡或决策

此时任务已准备就绪，可通过

/do-task <id>

进行实施。