task-start

Task Start

Before writing code, first ensure you're "doing the right thing" (requirement alignment), then "do the thing right" (solution design).

---

Step 1: Decision Tree — How deep does this task need to go?

After receiving a user requirement, judge according to the following decision tree:

收到需求
  │
  ├─ 任务明确且改动 ≤2 个文件？
  │   └─ YES → 【直接动手】跳过本 skill，按 CLAUDE.md 基本流程执行
  │
  ├─ 任务有模糊点但规模不大（≤3 文件）？
  │   └─ YES → 【仅对焦】执行第二步的需求对焦，然后直接开发
  │
  ├─ 从头开发完整前后端系统 / 包含多个页面的项目？
  │   └─ YES → 【全流程强制】对焦 + UI 原型 + 方案 + task-execute + task-finish，每个环节不可跳过
  │
  ├─ 任务涉及 3+ 文件 / 新模块 / 技术选型 / 架构决策？
  │   └─ YES → 【对焦 + 方案】执行第二步 + 第三步（条件触发）+ 第四步
  │
  └─ 不确定？
      └─ 先花 2 个工具调用了解任务范围，再回到决策树判断

Quick Judgment Signals：

Signal	Path
User says "change xxx", "add xxx"	Most likely just do it directly
User says "implement xxx feature", "help me build xxx"	Most likely needs alignment
User says "design xxx system", "refactor xxx"	Almost certainly needs alignment + solution
User says "build an xxx system", "set up from scratch"	Full process mandatory: task-start(alignment+UI prototype+solution) → task-execute → task-finish
User's description contains "roughly", "similar to", "about"	Alignment required

---

Step 2: Requirement Alignment (Align Before Act)

Align requirements before writing code. Asking proactively costs 100 times less than guessing wrong and reworking.

Alignment Checklist

Before entering Plan mode or writing code, confirm that the following questions have answers:

#	Question	Purpose
1	Core goal: What problem does this requirement solve? Who uses it?	Avoid building something "technically correct but unwanted by users"
2	Acceptance criteria: To what extent counts as "done"?	Prevent over-implementation or missing key scenarios
3	Input/output: Where does the data come from? What form is the output?	Clarify interface boundaries
4	Boundaries and exceptions: What to do about null values, concurrency, errors?	Identify hidden complexity in advance
5	What not to do: What looks related but won't be done this time?	Draw clear scope to prevent expansion
6	Dependencies and constraints: Existing logic or technical constraints that must be compatible?	Avoid discovering incompatibility after finishing

Historical Experience Retrieval (mandatory before alignment)

Before starting alignment, retrieve historical experience from two sources:

Source 1: docs/decisions/(project-level experience, git-managed)

# 搜索相关关键词
grep -r "相关模块名/功能名" docs/decisions/

Source 2: memory(cross-project experience, cross-session index)

• Read the MEMORY.md index and check whether there are feedback/project type memories related to the current task
• Information in memory may be outdated; verify before referencing (check whether the file/function still exists)

If relevant experience is found:

• Proactively remind the user: "Last time I did something similar, I hit these pitfalls: ...", note the source (docs or memory)
• Incorporate historical experience into the clarification considerations to avoid repeating pitfalls

If not found: continue with normal clarification.

How to clarify

• Don't ask 6 questions at once: pick the 2-3 most uncertain ones and use AskUserQuestion to confirm
• State your understanding: don't vaguely ask "what do you want", but say "I understand you want X, and for edge cases I plan to handle it with Y, right?"
• Stop when there's enough information: 80% certainty is enough to start; verify the rest during implementation

Clarification dialogue examples

Bad clarification(vague, passive):

用户：帮我加一个用户导出功能
Agent：请问你想导出什么？格式是什么？有什么要求？

→ The questions are too scattered; the user doesn't know where to start answering

Good clarification(specific, proactively offering judgment):

用户：帮我加一个用户导出功能
Agent：我理解你要的是：
1. 在用户管理页面加一个"导出"按钮
2. 导出当前筛选条件下的用户列表，CSV 格式
3. 包含基本字段：姓名、邮箱、注册时间、状态

有两个点想确认：
- 导出数据量大吗？超过 1 万条的话需要考虑异步导出 + 下载通知
- 手机号等敏感字段需要脱敏吗？

→ First give your own understanding, then ask targeted key questions

Clarification conclusion output

After clarification is complete, organize the conclusion into a paragraph, format:

## 需求对焦结论
- 目标：[一句话]
- 验收标准：[具体条件]
- 不做：[明确排除的内容]
- 待定：[开发中再确认的点]

This conclusion is directly input into the "Background and Goals" section of the proposal, or used as input for Plan mode.

Update Backlog status (required after clarification is complete)

After clarification is complete and development is confirmed to start,immediately update the status of the associated backlog：

1. Find the corresponding requirement file in docs/backlog/ and update the frontmatter:status: in-progress
2. Update docs/backlog/INDEX.md: change that requirement's [ ] to [~]

If the current requirement has no corresponding backlog file (such as a temporary small requirement), skip this step.

---

Step 3: UI prototype confirmation (when frontend pages are involved)

For tasks involving UI, produce a previewable prototype before writing code. Changing a prototype costs 100 times less than changing implementation code.

Trigger conditions

Mandatory trigger(cannot be skipped):

• Developing a complete system including frontend from scratch
• Setting up a new project that includes multiple pages

Conditional trigger(execute when the following scenarios are involved):

• Creating a new page or view
• Making layout/structural changes to an existing page
• Involving a new interaction flow (forms, modals, step guides, etc.)
• The user explicitly mentions UI-related expectations

Not triggered: pure backend, pure logic, style fine-tuning (changing colors/spacing), tasks with an existing clear design draft.

Execution flow

需求对焦结论
  │
  ├─ 涉及 UI？ → NO → 跳到第四步（方案设计）
  │
  └─ YES ↓
     1. 生成 HTML 可预览原型（静态页面，重点是布局和信息结构）
     2. 用 preview 工具启动本地预览，让用户在浏览器中查看
     3. 用户确认或提出修改意见
     4. 迭代调整，直到用户确认 UI 方向正确
     5. 将确认后的 UI 方案写入技术方案文档的「UI 设计」部分

HTML prototype specification

• Goal: validate layout, information hierarchy, and interaction flow; don't pursue visual perfection
• Technical requirements: a single HTML file, inline CSS, no external resource dependencies
• Storage location：docs/prototypes/<模块名>-prototype.html, can be deleted after confirmation
• Content requirements：
  • Use real or near-real sample data (not lorem ipsum)
  • Annotate behavior descriptions of interactive elements (hover states, click navigation, etc.)
  • Display multiple pages/states using different sections or page switching
• Style: a simple gray-and-white color scheme is enough; the focus is structure, not aesthetics

Key points to align with the user

When confirming the prototype, proactively guide the user to focus on:

1. Information Architecture: What information is on the page? Is the hierarchy correct? Is anything missing or extra?
2. Layout: Is the overall arrangement reasonable? Are the key actions placed conveniently?
3. Interaction Flow: Is the path for users to complete the core actions clear?
4. State Coverage: Do empty states, loading states, and error states need to be handled?

Prototype Confirmation Conclusion

## UI 确认结论
- 页面结构：[确认的布局方案]
- 关键交互：[确认的交互行为]
- 用户反馈：[用户提出的调整及处理]
- 原型文件：[文件路径，供开发参考]

---

Step 4: Solution Design (Plan → Review → Do)

For large features and complex tasks, write the solution before writing code. Changing a document costs 10 times less than changing code. The actual writing of the solution is handled by writing skill(technical documentation mode); this step is only responsible for process orchestration.

Solution Output Process

对焦结论就绪
  │
  ├─ 需要选型？→ 调用 tech-evaluation skill，获得选型结论
  ├─ 需要调研？→ 调用 deep-research skill，获得调研结论
  │
  ↓ 信息就绪
  │
  ├─ 写技术方案（spec）
  │   → 调用 writing skill（技术文档模式 → spec 模板）
  │   → 输入：对焦结论 + 选型结论（如有）+ UI 确认结论（如有）
  │   → 产出：docs/specs/YYYY-MM-DD-<模块名>-<主题>.md
  │   → 模板详见 writing skill 的 references/templates/spec.md
  │
  └─ 写开发计划（plan）
      → 调用 writing skill（技术文档模式 → plan 模板）
      → 输入：spec 文档
      → 产出：docs/plans/YYYY-MM-DD-<模块名>-plan.md
      → 模板详见 writing skill 的 references/templates/plan.md

Solution Content Requirements

The solution must fully account for thebackground → research → validation → decisionfull chain (see the CLAUDE.md solution design specification):

Required Sections	Questions That Must Be Answered
Background and Motivation	Why do this? What problem does it solve?
Current State Analysis	How is it currently done? Where are the pain points?
Research and Alternatives	Which options were researched? What were the validation results for each?
Decision and Trade-offs	Which one was chosen? Why? What was given up?
Technical Solution	How exactly will it be implemented?
Risks and Boundaries	Known risks? What will not be done?

Review Checkpoints

During solution Review, focus on:

• Goals are clear, acceptance criteria are measurable
• Change scope is reasonable, no scope creep
• Technical choices are justified, not off the top of one's head
• Implementation steps are executable and have a sequence
• Risks are identified and have response plans
• No over-engineering, complexity matches the problem

Solution Change Management

If during development you find that the solution needs adjustment:

• Minor adjustment(fine-tuning implementation details): adjust directly, and sync at the next communication
• Medium adjustment(changes in step order, adding or removing changed files): pause development, update the solution, then continue
• Major adjustment(directional changes, overturning the core design): stop development and Review again

---

Connection with Other Skills

task-start（本 skill）— 启动：对焦需求 + [UI 原型确认] + 设计方案
  │
  ├─ 对焦前 → 检索 docs/decisions/ 历史经验（避免重复踩坑）
  ├─ 对焦结论 → 输入到方案的背景部分
  ├─ UI 原型 → 调 rapid-prototype skill 或存入 docs/prototypes/
  ├─ 涉及选型 → 调 tech-evaluation skill
  ├─ 需要调研 → 调 deep-research skill
  ├─ 写方案 → 调 writing skill（技术文档模式 → spec 模板）
  ├─ 写计划 → 调 writing skill（技术文档模式 → plan 模板）
  ├─ 判定为重构任务 → 引导走 refactoring skill
  │
  ↓
task-execute — 执行：持续编码 + 跨会话进度管理
  │
  ↓
task-finish — 收尾：CR 自检
  ↓ （需求彻底完成后）
task-manager 标 done — 复盘 + 经验沉淀 → docs/decisions/

If it is a large task spanning multiple sessions, also use the task-execute skill to track cross-session progress.

Mandatory Rules for Full-System Projects

When developing a complete front-end and back-end system from scratch, the following stages are all mandatory and none may be skipped:

Stage	skill	Actions That Must Be Completed
Requirement Alignment	task-start step 2	Go through the entire alignment checklist and output the alignment conclusion
UI Prototype Confirmation	task-start step 3	Generate HTML prototype → preview → user confirmation
Solution Design	task-start step 4	Complete solution document, saved to docs/specs/
Continuous execution	task-execute	Enable the progress tracking framework to manage cross-session context
CR self-check	task-finish	In-depth self-check mode, checking item by item
Retrospective consolidation	task-finish	Four-dimensional review + experience saved to memory