Project Convention Resolver

项目规范问题自动修复（project-convention-resolver）

> 定位：项目内规范问题的「接收 → 分类 → 路由执行 → 验证 → 归档」一体化 Skill > > 类比关系： > - issue-tracker → 记录问题（不执行） > - project-convention-resolver → 记录 + 自动路由执行 + 验证 > > 强绑定 Rule：R2 NOFABRICATION / R3 READFIRST / R7 CLOSEDLOOPREQUIRED

---

规范问题分类（五类）

A 类：产品规范偏差
  → 功能不符合产品定义中的闭环设计
  → 动线缺失入口/出口
  → 双层设计缺失（只有人层没有智能体层，或反之）
  → 产品文档描述与实际不符

B 类：技术架构规范偏差
  → 接口设计不符合技术架构.md 规范
  → 模块边界不清晰，违反关注点分离
  → 跨模块耦合过紧，扩展性风险
  → Schema/数据模型与规范不一致

C 类：代码规范/实现偏差
  → 命名规范违反（snake_case/camelCase 混用等）
  → 缺少必要的错误处理或测试
  → 安全漏洞（注入/越权/硬编码密钥）
  → 与产品文档描述不符的实现

D 类：文档规范偏差
  → 文档结构不符合项目规范（缺变更记录/版本号等）
  → 多个文档内容漂移（同一内容在不同文档中描述不一致）
  → README 与实际代码状态不符

E 类：Skill/Rule 规范偏差
  → Skill 描述不准确 / 触发词不对
  → Rule 有冲突 / alwaysApply 叠加矛盾
  → Skill 与实际行为不一致

---

激活后立即执行

Step 1  记录问题（R2：必须基于用户实际描述）
        调用 issue-tracker：
        - 如果是产品设计类 → 写入 产品经理/产品问题追踪台.md
        - 如果是技术实现类 → 写入 技术架构师/技术问题追踪台.md
        - 如果是 Skill/Rule 类 → 写入 .cursor/skills/skill-index/PENDING-EXPERIENCES.md

Step 2  Read 相关文档（R3 READ_FIRST）
        根据问题类型读取必要的上下文：
        A 类 → Read: 产品经理/产品定义.md
        B 类 → Read: 技术架构师/技术架构.md
        C 类 → Read: 被报告的代码文件（具体路径）
        D 类 → Read: 被报告的文档文件
        E 类 → Read: 被报告的 SKILL.md 或 .mdc 文件

Step 3  分类 + 确认修复方向
        向用户确认：
        「检测到 [X类] 规范问题：[问题描述]
          修复方向：[一句话说明]
          将调用：[对应角色 Skill / 工具]
          
          [确认，立即修复] [调整方向后修复] [只记录，暂不修复]」
        
        若用户选择「调整方向后修复」：
        → 等待用户说明调整内容
        → 重新展示调整后的修复方向
        → 再次确认后再执行
        
        不允许静默执行修复（规范修复可能有误判，必须用户知情）

Step 4  路由执行（按分类路由到对应角色 Skill）
        
        【A 类 → 按 role-产品经理 激活协议执行】
        将「规范问题描述 + 相关产品定义章节内容」作为本次 PM 任务的上下文
        按 role-产品经理 的步骤修复产品定义文档或设计逻辑
        
        【B 类 → 按 role-技术架构师 激活协议执行】
        将「规范问题描述 + 相关架构文档章节」作为上下文
        修复技术架构.md，若涉及产品意图，必须先回 PM 确认
        
        【C 类 → 按 role-后端开发 或 role-前端开发 激活协议执行】
        将「规范问题描述 + 具体代码文件路径 + 违反的规范条目」作为上下文
        修复代码后自动触发「Bug 修复后强制验证闭环」（调用 /verifier）
        
        【D 类 → 按 doc-consolidator 激活协议执行】
        将「规范问题描述 + 涉及的文档文件」作为上下文
        整合/修复文档，确保单一真源
        
        【E 类 → 加载 skill-rule-修改规范，强制三问+备份+修改+变更记录】
        E 类不允许直接修改，必须先回答三问，再备份，再修改

Step 5  验证修复效果（R7 CLOSED_LOOP_REQUIRED）
        
        C 类（代码修复）：
        → 自动调用 /verifier，传入原问题描述作为验证场景
        
        A/B/D/E 类（文档/规范修复）：
        → 人工确认：「已完成修复，请确认以下变更是否符合预期：[变更摘要]」
        → 等待用户确认
        → 若本次修复来源为 skill-system-health-check 报告 → 修复完成后，告知：「建议重新运行 skill-system-health-check 验证该问题已消解」

Step 6  归档关闭
        → 更新追踪台对应条目状态为「已修复（含修复说明）」
        → 告知用户：「规范问题已修复并验证，追踪台已更新。」

---

路由决策树

用户报告规范问题
  ↓
判断问题类型
  ↓
├── 涉及产品功能/用户动线/闭环 → A类 → role-产品经理
├── 涉及接口/架构/模块边界 → B类 → role-技术架构师
├── 涉及代码文件 → C类 → role-后端/前端 → verifier
├── 涉及文档组织/版本/内容 → D类 → doc-consolidator
└── 涉及 Skill/Rule 文件 → E类 → skill-rule-修改规范

---

常见失败模式

失败模式1：用户描述的「规范问题」实际上是「功能需求」，而不是现有规范的偏差 → 预防：Step 3 确认时，区分「当前已有规范要求X，实现做了Y」vs「希望新增规范要求Z」 → 如果是新需求 → 路由到 role-产品经理 但不走修复路径，走功能设计路径

失败模式2：A/B 类规范修复后，未同步检查是否引起连锁影响 → 预防：B 类技术架构修复后，提示「架构变更可能影响已有代码，建议运行 role-测试工程师 关卡C」

失败模式3：E 类 Skill/Rule 修复被静默执行，未通过三问+备份 → 预防：E 类强制要求先加载 skill-rule-修改规范，不允许跳过

---

与现有组件的关系

| 组件 | 关系 | |---|---| | issue-tracker | 本 Skill 先调用 issue-tracker 记录，再继续执行（issue-tracker 是本 Skill 的 Step 1）| | role-产品经理 | A 类问题的执行 Skill | | role-技术架构师 | B 类问题的执行 Skill | | role-后端/前端开发 | C 类问题的执行 Skill | | doc-consolidator | D 类问题的执行 Skill | | skill-rule-修改规范 | E 类问题的执行 Skill（不绕过，必须经过）| | verifier | C 类代码修复后的验证 | | architecture-gap-mapper | B 类问题分析时可选调用 |

v1.0 → v1.1 — 2026-03-22 — Step 5 E类补修复后重验证建议（GAP-SK017-2 修复）

根因：scenario-sandbox-builder Phase 2 验证（SK-017沙盘）发现：Step 5 A/B/D/E类修复完成后只做人工确认，缺少「修复后重新运行 skill-system-health-check」的闭环验证步骤。导致Skill体系健康检查发现的P0问题修复后无法自动验证是否真正消解。

修改内容：

• 修改：Step 5 A/B/D/E类 → 在「等待用户确认」后追加：若修复来源为 skill-system-health-check 报告，建议修复完成后重新运行健康检查验证
• 备份路径：history/SKILL_v1.0_20260322_before_sk017b.md

验证方法：E类修复完成后，Skill 应提示「建议重新运行 skill-system-health-check 验证该问题已消解」 验证状态：🔵 待验证

---

注意事项

• Step 3 必须等用户确认：不允许静默执行修复，规范修复可能有错误判断
• E 类不能绕过 skill-rule-修改规范：Skill/Rule 修改的三问+备份是强制要求
• B 类架构修复必须回 PM 确认：技术架构变更可能影响产品定义，必须 PM 知情
• C 类代码修复后强制 verifier：遵循 role-后端/前端开发 的「Bug 修复后强制验证闭环」规则

---

变更记录

v1.0 — 2026-03-19 — 初始创建

根因：项目内规范问题缺少「接收→分类→路由执行→验证」的完整链路。issue-tracker 只记录不执行，规范修复依赖用户记忆力手动触发对应角色 Skill。本 Skill 补完这个链路，使项目规范问题的处理与 Skill 体系自驱机制对等。

强绑定 Rule：R2 NOFABRICATION / R3 READFIRST / R7 CLOSEDLOOPREQUIRED

验证状态：🔵 待验证（关卡A/B/C 已通过设计阶段模拟）

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TashanGKD
• Source: TashanGKD/tashan-cursor-skills
• License: MIT

Install and usage instructions live in the source repository linked above.