| name | writing-plans |
| description | Use when Planning Gate triggers (affected files ≥3 or public API change) and an implementation plan is needed |
Writing Plans
Type: Technique | Discipline: Rigid
指导如何写好一份实施规划。Planning Gate（见 using-growingio-sdk-skills meta-skill）定义 plan 的格式（四节结构），本 skill 定义内容质量。
核心原则： 写 plan 时多想 10 分钟，实施时少返工 1 小时。
何时触发
Planning Gate 要求输出 plan 时（影响 ≥ 3 文件，或涉及公开 API 变更）。
影响面自查清单
按改动类型对照清单列全受影响的文件/路径，漏一项 = 返工：
| 改动类型 | 必须同时覆盖 |
|---|
| 公开 API 新增/改/删 | Index.ets + obfuscation-rules.txt + docs/GrowingAnalytics/interfaces/*.md（涉及 SaaS 差异加 README_SaaS.md） |
| 事件字段变更 | SaaS（JSON MPv2）+ NewSaaS（Protobuf）+ CDP（Protobuf）三产品线在"影响产品线"列显式标注 |
核心模块 (core/ event/ autotrack/) | 实现文件 + *.test.ets 单测 + docs/GrowingAnalytics/<module>/*.md |
| GrowingConfig 变更 | NewSaaS / SaaS / CDP 三种工厂方法的默认值 + copy() 校验逻辑 |
| autotrack 改动 | Native / Hybrid / Flutter 三场景 + SaaS 模式不支持无埋点，路径上显式跳过 |
| session 改动 | 前台触发 + 后台 APP_CLOSED + sessionInterval（30s）超时逻辑 |
| 事件上报改动 | Protobuf 路径 + JSON 路径 + compressEnabled / encryptEnabled 开关 + eventSequenceId |
| 生命周期与线程 | UIAbility onForeground/onBackground + 主线程零阻塞（IO 走 TaskPool） + dataCollectionEnabled 开关尊重 |
任务拆分
拆成多任务： 变更逻辑独立且可并行 / 单任务描述 > 200 字还说不清。
合并为单任务： 接口与其使用者（拆开编译不过） / 同模块内部重构 / TDD 内测试与被测代码。
拆分后按 subagent-driven-development skill 判定是否走 subagent 模式。
Rationalizations
| Excuse | Reality |
|---|
| "plan 写得越细越安全" | 过度设计 = 浪费；plan 划边界和决策点，不是代码草稿 |
| "先动手改两个文件再补 plan" | ≥3 文件动手那刻已经违规 |
| "影响文件只列改到的源码" | 文档 / 混淆规则 / 测试都算影响，漏一个就返工 |
"公开 API 改只动 Index.ets" | 三件套缺一即规格不完整 |
| "事件字段只影响当前产品线" | 三产品线字段要求不同，未标注 = 后端仓库出错 |
| "autotrack 不用管 SaaS" | 必须显式声明"SaaS 跳过"，否则会出现错误降级分支 |
| "这次规划口述就行" | 必须落地到 docs/plans/YYYY-MM-DD-*.md，reviewer 要读文件 |
Red Flags — STOP if you catch yourself thinking these
- "先改两个文件试试，plan 后面再写" → Planning Gate 触发那一刻就必须先写 plan
- "影响面我心里有数，不用列全" → 没列出来的文件 = 会返工的文件
- "这个字段变更只涉及 NewSaaS" → 三产品线必须逐一确认，未标注 = 后端出错
关联 skill
- 上游触发： 控制器判定 Planning Gate 触发
- 调度 subagent： 无（控制器直接执行）
- 完成后交接：
plan-document-review → 用户确认 → subagent-driven-development 或直接实施
- 替代路径： 未触发 Planning Gate → 跳过本 skill，直接实施 +
sdk-code-review 独立审查
