用途
gstack-plan 是一个用于功能开发前的规划评审技能。它的定位不是写代码，而是评审计划：在构建功能之前先挑战范围，然后按架构、代码质量、测试、性能四个部分进行工程审查，最终产出一份可以照着执行的构建计划。
工作方式
用户需要先提供计划或功能描述；如果没有提供，技能会要求补充并停止。
开始时进入仓库，执行以下命令了解现状：
git log --oneline -10 ls
随后阅读计划涉及的文件。评审按顺序进行：先做范围挑战（Scope Challenge），再依次完成第 1 至第 4 部分。对每个发现给出严重程度、建议和替代方案。若某些决策会改变范围，会在一条消息中集中提问，并等待用户回答。最后给出修订后的计划：构建什么、按什么顺序、涉及哪些文件、用什么测试验证，以及哪些内容不在范围内。
工程偏好
技能内置了以下工程偏好，用于指导建议：
- 共享代码：需要具备共同行为并带来可靠性提升或净节省；仅外观相似不足以抽取。
- 测试：每个行为都有测试；没有回归价值的测试不写。
- 足够工程：避免脆弱性以及过早抽象和复杂化。
- 边界情况：优先彻底处理，而不是追求速度。
- 显式优于聪明。
- 差异适度：采用最小清晰改动；必要时可以重写破损的基础。
- 数据模型：存储依据数据的查询、完整性规则和更新边界，而不是文件数量；独立查询、约束或更新的字段应有明确列或表，JSON 适合整体读写的文档。
范围评估
在提出范围变更之前，先完成以下检查，且不立即写入计划：
- 每个子问题是否已有现成方案：检查辅助函数、库、调用方和可复用产出，并考虑行为与依赖/部署边界。引用已有来源；对提议的调用方标注其对应的计划需求和假设。
- 达成目标的最小改动是什么：标记可以延后而不阻塞目标的工作，挑战范围蔓延。
- 复杂度检查：统计选定工作中的文件数、新类/服务数（每个只计一次，估算值需标注）。若达到 8 个以上文件或 2 个以上新类/服务，应提出更小的安排并在变更范围前询问。
- 分发检查：对于新产物，核实构建/发布 CI/CD、目标操作系统/架构和下载/安装渠道；延后项写入“不在范围内”。
四个评审部分
范围达成一致后，依次评审架构、代码质量、测试、性能，不得压缩、缩写或跳过任何部分，包括策略、规格或基础设施计划。
1. 架构评审
评估系统与组件边界、依赖与耦合；数据流、瓶颈、扩展性和单点故障；安全（认证、数据访问、API 边界）；计划中需要 ASCII 图的关键流程；每条新路径/集成的一个现实生产故障，计划是否处理；新产物的构建、发布和更新路径及 CI/CD 是否包含或延后。
当计划引入新模块、服务、包或边界（即其他代码会调用的公共表面）时，执行“两种形态”（design-twice）：要求提供结构上不同的第二种形态（状态由不同方持有、职责划分不同或边界位置不同），仅在第一种形态内做点修复不算第二候选。若计划没有第二种形态，用五行草拟一个（类型和签名，不实现函数体）并记为替代方案。比较时看接口深度：在多大的公共表面后隐藏了多少行为和策略，优先隐藏更多而表面更小的方案。深模块不是深调用链：调用链把理解分散到各层，模块把理解集中在一个接口后。
第 1 部分结束前，用“八个红旗”筛查选定的形态（假设下一位贡献者是只看到所打开文件的智能体，会复制最近的示例并走最短可编译路径；优先选择从一个文件看正确的改动对整个仓库也正确的设计）。红旗是带文件或符号及修订理由的发现，而不是提醒注意的评论：
- 浅模块：大接口隐藏很少复杂度，每次操作多次调用，选项暴露内部阶段。
- 信息泄漏：一个决策（表示、策略、传输或存储细节）存在于多个模块；重新导出的传输类型属于泄漏；在边界处将外部数据解析为领域类型。
- 时序分解：按执行顺序（加载、校验、转换、保存）拆分模块，而不是按所拥有的知识拆分。
- 传递方法：函数以相同形状转发相同参数；删除它或移动职责。
- 所有权分裂：两个模块写同一状态或各存一份副本；每份状态只有一个所有者。
- 一件事两种做法：智能体会复制先遇到的写法；保留一种，移动调用方并在同一改动中删除其余。
- 可导入的内部实现：最短可编译路径会导入它们并使其成为接口；让外部导入导致构建失败。
- 手工同步列表：同一列表出现在两处；派生第二处，或在两者不一致时让构建失败。
在架构部分记录：两种形态、选择、支撑选择的深度论证，以及每个红旗及其修复。
2. 代码质量评审
评估组织与模块结构；目标及相关调用方中的共享代码机会（不做独立的历史/PR 扫描或配额，检查提议的调用方假设是否与现有接口一致）；明确标记错误处理缺口和缺失的边界情况；按工程偏好指出技术债、脆弱性和不必要的复杂度；被触及文件中 ASCII 图的准确性。
3. 测试评审
对于共享代码变更，审计现有/缺失的共享契约测试（行为、错误、副作用、边界）以及每个迁移调用方的集成/差异。被拒绝的抽取仍需要覆盖真实重复代码缺陷。对于计划中的每个新代码路径、分支和错误路径，指明证明它的测试（单元、集成或端到端）以及它能捕获的回归。缺失的测试成为计划项。
4. 性能评审
评估 N+1 查询和数据库访问模式、内存使用、缓存机会、缓慢或复杂路径。在每请求或循环路径上，检查循环中的查询、无界查询或缓存、缺失索引、整文件加载和无超时阻塞调用。对每个发现给出规模（行数、请求/秒、字节数）或标记为未知；不得编造基准数据。
适用场景与限制
适用于功能开发前的计划评审、架构与代码质量把关、测试覆盖规划和性能风险排查。它不构建功能，不替代实际编码；需要用户提供计划或功能描述才能开始；部分结论依赖仓库内实际代码与调用方信息。