skill-gap-analysis

name	skill-gap-analysis
description	Skill 缺口与大语料分析 Owner — 当任务涉及项目/工作区产物扫描、能力盘点、缺少哪些 Skill、全量审查前规模判断、大目录分批、抽样深读、扫描恢复或自我进化候选发现时使用；要求先识别项目并形成规模决策，再进行有边界的证据扫描。

Skill Gap Analysis

职责

在分析、审查或能力盘点前先判断目标项目和语料规模，再选择一次性、分批、抽样深读或阻断路线；完成扫描后，把领域信号与现有 Skill Owner、消费者和验证路线交叉去重，形成可复证的缺口决策。

ProjectArtifactScaleRoutingGate

任何 broad scan 前必须按顺序执行：

1. 识别唯一 project / root / activeRoot；未识别时停止，不得扫描整个工作区。
2. 只做 bounded inventory，显式排除 node_modules/dist/cache/tmp/backup/smoke/deploy mirror 等派生产物。
3. 统计 relevantFileCount / parseableBytes / largestFileBytes / directoryConcentration / derivedArtifactRatio / consumerFanOut。
4. 形成 ScaleDecisionRecord，再允许内容读取或递归检索。

WorkspaceRootScanHygiene（C16 / PI-20260724-01 · 范围与成本规则）

🔴 未绑定唯一项目前，禁止对 workspace/monorepo 根发起递归 inventory。项目路径已知时，禁止再从 workspace 根 -Recurse 查找。

禁止	允许
Get-ChildItem <workspaceRoot> -Recurse（含 -Depth ≥1、按名 Filter 全树搜）	list_dir 仅一层；Test-Path <workspaceRoot>/<project>
dir /s <workspaceRoot>、find <workspaceRoot> 无项目前缀	在已绑定 project root 内有界 Recurse，且排除 node_modules/dist
为「找项目」扫整个 E:\Worker 等 monorepo 根	用户 @path / 已知子目录名 / Profile inventory
inventory 展开 node_modules、文档站 doc_build、巨型 dist	显式 -Exclude / 工具默认尊重 gitignore 的列表

机器探针：scripts/lib/host-parity-scorecard.js → classifyWorkspaceRootScanSample（workspace-root-recurse = 范围/成本缺陷）。Hook 侧对命中 workspace 根 + Recurse 的 shell 只发出 advisory；执行权限由宿主及其用户配置决定（见 lifecycle-dangerous-command）。

TimeToFirstValueGate（TTFV · 与 compliance/C16 联防）

非 chat 在入口检查与最小 ContextReadPlan 之后，同一用户可见回复必须至少交付其一，否则本轮视为扫描/准备违规：

1. 可确认的半屏范围卡（路径/批次/排除项）；或
2. 首批 finding / 分析结论 / 可执行方案要点；或
3. 明确阻断（项目不明、权限、环境缺失）+ 恢复动作。

禁止：整轮只读 Skill 百科、只跑全库 inventory、或只写超长需求概括却零交付。用户明确「直接开审/跳过确认」时跳过范围确认，立即 B1 交付。

ProgressReportFastPath（PI-20260725-01 · TTFV 进度查询特化）

🔴 用户问「进度 / 发版到哪了 / 验证状态」且已点名项目时，禁止 workspace 根 inventory 与模糊 task 名阻塞首答。

步骤	要求
绑定	立即绑定 .devcodex/<project>/ 与源码目录；路径直达
真相源顺序	① verification/issues/README（或问题总台账）② fixed-awaiting-rerun-classification（若有）③ profile 发布/项目检查点 ④ SUMMARY 近行 ⑤ 仅不足时再读 05-实施进度/报告
首轮交付	需求定位 → 进度数字表 → 当前阻断 → 一句话结论
失败	同 TTFV 违约；探针 classifyProgressReportFastPathSample → progress-fail

机器探针：scripts/lib/executable-absorption-gates.js → classifyProgressReportFastPathSample；npm run test:executable-absorption-gates。

decision	默认判定	执行
single-pass	全部满足 ≤50 files、≤2 MiB、largest≤256 KiB、fan-out≤10，且用户未提示大目录	一次处理，仍保留排除策略
batched	任一中等规模、fan-out>10、控制面联动或用户提示目录大	按 namespace/目录/文件预算分批，逐批写 checkpoint
sampled+deep-read	>500 files、>20 MiB、derived ratio>30% 或目录极端集中	全量 inventory + 强语义检索 + 代表文件深读；禁止声称逐字全读
blocked	项目/root 不唯一、排除边界不可信、权限/文件系统错误	停止 broad scan，先恢复边界

项目 Profile 可以配置更保守阈值，不得放宽上述默认边界；用户明确“大目录/文件很多”时不得降为 single-pass。

ScaleDecisionRecord

至少记录：project、root、activeRoot、inventoryCommand、六项规模指标、decision、reason、exclusionPolicy、batchBudget、checkpointPath、timeoutRetry、invalidRunPolicy。

• 非 single-pass 缺 checkpointPath 或 batch budget 时不得继续。
• timeout、错误 glob、派生产物污染或无法解释的数量跳变必须标记 invalid/discarded，不能进入结论。
• 检查点状态使用 not-started / running / accepted / invalid / blocked；恢复只从最后一个 accepted 批次继续。

Skill 缺口分析流程

1. 生成 WorkspaceCorpusManifest 与 ExclusionPolicy。
2. 按规模决策执行 BatchEvidenceLedger，每批记录输入、命令、文件数、有效信号和异常。
3. 宽口径召回后执行强语义复扫、词边界校准、代表文件深读和历史镜像降权。
4. 建立 ExistingSkillCoverageMatrix：候选 → 最接近 Owner → 未闭合边界 → current consumer → validation。
5. 执行 CommonNormGeneralizationGate 与消费者证明；项目局部信号标为 project-local / case-evidence-only。
6. 为每个真正缺口冻结 trigger、ownedArtifacts、consumerSync、validationRoute 和负向样例。
7. 至少完成两轮维度不同的 omission-only 零新增，写入 ConvergenceRecord。

输出产物

产物	必填内容
WorkspaceCorpusManifest	namespace、路径类型、文件/字节、派生边界
ScaleDecisionRecord	规模指标、四态决策、预算与理由
BatchEvidenceLedger	批次、checkpoint、命令、状态、invalid-run
ExistingSkillCoverageMatrix	候选与现有 Owner 的覆盖/重叠/缺口
CapabilityGapDecision	new-skill / existing-subgate / docs-only / reject
ConvergenceRecord	每轮维度增量、新增数、连续零新增

所有覆盖结论同时执行 audit-common 的 ReviewCoverageClaimIntegrityGate。WorkspaceCorpusManifest 只能证明 inventory-covered；关键词检索只能证明 machine-scanned；代表文件深读必须明确 sampledSet/unreadSet/inferenceBoundary。只有逐文件 FileEvidenceLedger 才能声明逐字全读。

与 incremental-project-analysis 分界

本 Skill	incremental-project-analysis
规模路由、corpus inventory、Skill 缺口 vs Owner	知识快照、digest 失效、BatchProgress 强制交付、GlobalBacklog、精度合同、双层验证
「怎么分批扫、缺什么能力」	「扫完的事实如何复用、如何对用户分批交付与综合」

batched / sampled+deep-read 的 analyze 路径在形成 ScaleDecision 后应同时调用 incremental-project-analysis 的交付与精度门禁；本 Skill 不把快照状态机整坨并入。

反模式

• 未识别项目就从 workspace root 递归扫描。
• 项目名已知仍对 monorepo 根 Get-ChildItem -Recurse -Depth N 找目录（PI-20260724-01 复发样例）。
• 先全量扫描超时，再补写“应该分批”。
• 把备份、安装包、浏览器 Profile、translation cache 或 lockfile 当能力证据。
• 只按关键词计数，不读代表样本、不反查现有 Skill。
• 用抽样深读结果宣称“逐字审查所有文件”。
• 同一批次失败后继续沿用部分输出，或用后续成功命令覆盖前序失败。
• 做完分批扫描却不调用 incremental Skill，导致无 ProgressCard / 无快照 / 假完整主题清单。
• 首轮用户可见回复只有流程/Skill 预热、无范围卡/finding/阻断（TTFV 失败）。

验证

至少包含：小项目 single-pass 正向、用户大目录强制 batched、>500 文件 sampled+deep-read、unresolved project blocked、错误 OR glob、派生污染、timeout 无 checkpoint、历史 already-fixed 未去重等正负向样例。