> 族内折叠指针（技能质量管理族 · 治理段）
> 本技能已归入 zfl-skill-governance（本段唯一入口）。日常使用请从主技能进入。
> 目录与脚本资产保留，供主技能及其他技能直接调用，请勿重复实现本技能已有能力。
约束与错误处理
- 本技能仅处理其声明范围内的任务，不越界执行未授权操作。
- 错误处理：输入不合法时返回明确错误说明，不静默跳过；依赖缺失时降级提示并给出替代路径。
不适用场景（谁不该用本技能）
- 想要一键自动化迭代的：本技能是文档 SOP，不是可执行工具；自动化编排入口在族内主入口
zfl-skill-governance。 - 手头没有评测报告或质量扫描结果的：先跑
zfl-skill-quality-checker拿 P0/P1/P2 清单（或等 SkillHub TRACE 报告），空手迭代没有锚点。 - 单点小修（改错字/补一行/改一处报错文案）：直接改 + 复扫即可，不值得走全流程。
- 目标不是带 SKILL.md frontmatter 的 zfl- 技能包：模板骨架按 zfl- 生态约定设计，其他结构需自行变通。
能力矩阵速查（能做什么 / 边界 / 不适用）
| 能做什么 | 边界 / 限制 | 不适用 |
|---|---|---|
| 把 TRACE 报告拆成可落改项 | 需先有报告或质检清单，空手无锚点 | 空手泛泛提质 |
| 判真假短板、给洼地分层排序 | 提供判据，不替代人工复核 | 需改代码的功能层缺陷（要回归预算） |
| 提供可抄骨架（err_card/能力矩阵/FAQ/边界段/五源清单） | 骨架需按目标技能填充 | 非 zfl- 结构、无 SKILL.md 的包 |
| 串起复扫 / 升版 / 发布三步命令 | 调外部工具，非本技能自带执行能力 | 想要一键自动化跑完的 |
批量拉取全生态 TRACE 分并出优先级队列（scripts/ 三件套） |
只读公共 API，不发布不修改；分数为五维均值估算 | 需要平台官方综合分精确值（不暴露） |
落改失败分支排查（每步卡住怎么办）
| 步骤 | 卡点现象 | 处理 |
|---|---|---|
| 取报告 | /evaluation 无数据或版本不对 |
新包刚发布需等待重扫；先用 quality_checker 拿 P0/P1 清单顶上 |
| 辨真假 | 扣分点含糊、像误判 | 回实物读一遍；查 FAQ Q7/Q11 与 OPEN 台账（BP1/BP4） |
| 钉基线 | 线上版本 ≠ 本地 VERSION | 以线上 latestVersion 为准，先对齐再改，别在陈旧基线上动手（BP5） |
| 落改 | 主文档塞不下新内容 | 下沉 references/，正文留指针（BP8/FAQ Q13） |
| 复扫 | P1 残留清不掉 | 先判归因：真短板记入下一轮不硬清零（BP10）；守卫假阳（三源明明一致却报红）须回读守卫源码修判据、勿在技能里回避关键字（FAQ Q21/PF-714） |
| 升版 | CHANGELOG 密度门禁拒收 | 「现象→修复」句式 + 反引号标识符 + 具体数字 |
| 发布 | 匿名视角仍是旧版 | 传播窗 ≥8min，定时复验，严禁重推（BP12/PF-202） |
输出与格式
- 输出格式：结构化文本，包含明确的章节划分与关键结论。
- 输出结构：按任务类型返回对应格式，确保可读性与可追溯性。
扩展用法：批量取分与生态级短板定位（SOP 第 0 步）
单个技能迭代是「点」，批量取分才能看出「面」——哪个维度是生态通病、哪些技能该优先动。
三步流水线（脚本在 scripts/，零外部依赖，只读不写远程）：
- 批量取分
scripts/fetch_trace_batch.py
---prefix zfl-按目录前缀批量；--slug X --slug Y指定；--limit 8小样本试跑
- 自动从各技能_skillhub_meta.json取 slug（skillName优先）
- 输出 JSON：五维均值、全部分项分、最低分项、stats、拉取状态 - 横向分析
scripts/analyze_trace_batch.py
- 五维横向对比 → 定位系统性短板维度
- 分项聚合（跨技能同名 item 求均值）→ 定位最洼具体子项
- 区分度分析（高分组 vs 低分组差值）→ 定位抬分杠杆
- 迭代 ROI 队列（低分 + 下载量）→ 排优先级 - 出看板/报告
scripts/gen_trace_dashboard.py→ 自包含 HTML + Markdown
已验证的生态结论（2026-10-01，63 个已发布 zfl- 技能）：
- 系统性短板 = R 可靠性 4.39 / C 规范性 4.43；T 可信任度 4.95 已饱和，别再投入
- 最洼分项 = convention.antiPatternFaq 4.19、reliability.errorHandling 4.26
- 第一抬分杠杆 = reliability.errorHandling（高/低分组差 +0.97）
→ 结论：优先补「错误处理说明」与「反模式/FAQ」，比全面修补性价比高一个量级
两条取数陷阱（实测，别踩）：
- 未发布技能无分属正常：本地 _skillhub_meta.json 的 source=local 即未发布
（实测 115 个 zfl- 目录里 63 个 skillhub（全部有分）、52 个 local（全部无分），零交叉污染）
- 同一 slug 可能 /evaluation 返回 200 而 /api/v1/skills/<slug> 返回 404
（未公开/已下架）→ 此时下载量/版本取不到，必须标「未知」，不可当 0 参与排序
示例（TRACE 评测短板 → 复盘落改 → 复评进入下一轮）
场景：收到某技能的 SkillHub TRACE 评测报告，短板集中在 R/A/T 维，要以产品经理视角系统化提质。
1. 读报告定位短板：对照 TRACE 五维，把 R/A/T 维扣分点逐条拆成可执行的整改项；含糊扣分先查 references/FAQ.md 辨真假短板。
2. 照模板落改：按 references/templates.md 的 err_card/能力矩阵/FAQ 骨架，把整改项回填到 SKILL.md 与 references/。
3. 复评收敛：跑 quality-checker 复扫，P0/P1 清零才算这一轮收口；残留短板记入下一轮轨迹。
4. 下一轮：更新 CHANGELOG 与版本号，回到主入口 zfl-skill-governance 排队。
落改执行清单（照抄逐条执行，不靠临场理解）
- 读报告：把各维扣分点逐条抄成整改项；含糊扣分先查 FAQ Q7 辨真假短板。
- 分层排序：文档/UX 层（改表述/补文档/加示例）优先，功能层（改代码）需回归预算后排（FAQ Q12）。
- 落改前钉基线：
api.skillhub.cn/api/v1/skills/<slug>核对线上版本与本地 VERSION 一致，防在陈旧基线上白改（FAQ Q17）。 - 照 templates.md 骨架回填（目录见文件顶部）；一文件一轮一 Edit。
- 复扫收敛：quality_checker
--fail-on P0，P0/P1 清零才算本轮收口；残留记入下一轮轨迹。 - 升版：bump_version 带「现象→修复」句式 CHANGELOG，过密度门禁；
_skillhub_meta由发布链路回写（PF-487）。 - 发布：publish_gate
--yes --native；发布后 ≥8min 匿名复验，禁因匿名旧版重推（PF-202）。 - 沉淀：新坑入坑点库、复盘入日志，再进下一轮。
实际命令形态（<skills_root> 为技能根目录占位符）：
rem 1) 打开落改模板（err_card / 能力矩阵 / FAQ 骨架），照骨架回填
type <skills_root>/zfl-skill-trace-iterate/references/templates.md
rem 2) 落改后复扫（P0/P1 清零才算这一轮收敛，否则带残留短板进下一轮）
python <skills_root>/zfl-skill-quality-checker/scripts/quality_checker.py --skill-dir <目标技能目录> --fail-on P0
