expert-output-quality

name	expert-output-quality
description	专家型产物质量门禁 — 当任务涉及代码、文档、示例、fixture、quick start、技术方案、报告或用户指出“不专业 / 像初级 / 示例误导 / 没有资深架构视角”时使用；要求区分生产推荐路径、框架原生能力、测试夹具边界、反模式与证据矩阵。

Expert Output Quality Skill

定位

本 Skill 防止 AI 产物停留在“能跑示例”或“解释 fixture”的初级层面。它要求代码、文档、示例、方案和报告体现技术专家、资深架构师或领域专家视角：先给生产推荐路径，再说明测试夹具、演示代码、兼容路径和反模式的边界。

触发条件

场景	是否触发
代码、文档、示例、fixture、quick start、README、站点文档、技术方案、报告需要交付给用户或维护者	必须
用户指出“不专业”“像初级”“这不是推荐写法”“示例误导”“怎么又写成开发文档”	必须
文档或报告需要解释测试 fixture、demo、mock、兼容路径、历史写法或反模式	必须
框架、SDK、库、运行时、权限、路由、中间件、鉴权、缓存、事务、队列、ORM、UI 组件等存在原生能力	必须
纯内部临时草稿、只读事实查询、无需产物沉淀的短问答	N/A + skipReason

核心门禁

Gate	要求	证据
ExpertOutputQualityGate	输出必须体现对应角色的专业判断，不只复述代码或示例现象	角色定位、推荐路径、风险和取舍
ExpertRoleBaselineGate	根据任务选择技术专家 / 资深架构师 / 领域专家 / 产品化文档作者视角	角色与受众说明
ProductionRecommendedPathGate	先写生产推荐路径，再写测试、demo、fixture、兼容或历史路径	recommendedPath / nonRecommendedPath
FrameworkNativeCapabilityFirstGate	先检查框架、SDK、平台或项目现有能力，避免手写重复机制	official / repo-local / runtime evidence
FixtureBoundaryDisclosureGate	fixture、mock、样例配置、硬编码单例必须标明不是生产主路径	fixtureBoundary、allowedUse、forbiddenUse
ExampleArchitectureFitnessGate	示例要符合项目推荐架构，避免在 route、controller、UI 或测试里重复声明框架已承载的资源配置	architectureFit、consumerImpact
AntiPatternContrastGate	必要时列出“错误写法 / 为什么错 / 正确写法”，但不把反模式放成主路径	antiPattern、replacement
ExpertEvidenceMatrixGate	关键建议必须绑定代码、类型、官方文档、运行时、测试、构建或用户路径证据	evidenceMatrix
OperationExplanationContractV1	面向用户或维护者的操作说明必须写清目标、前置条件、输入、状态影响、结果形态、结果来源、失败语义、下一步和证据	operationId、userGoal、resultSource、failureSemantics
ResponseProvenanceClosureGate	报告和最终回复中“已完成 / 已验证 / 推荐”的结论必须能追溯到文件、命令、测试、运行时或用户确认来源	resultSource、evidence、freshness
MeasuredVerificationStandard	将探针/validate/测试标为已验证时，必须走生产入口命令（如 npm run test:core、node scripts/test-spec-governance.js）并记录 exitCode；隔离 harness 未复用 createCanonicalAwareReader 时只能标非权威实验，不得写成 V84/V# 成败	command、exitCode、authorityPath、parityEvidence
CodeTruthEvidenceMatrixGate	重要需求、技术方案和修复结论必须绑定 repo path、符号/契约、当前行为、反证探针和差距，不能只靠文档自洽	repoPath、symbol、currentBehavior、negativeProbe、gap
SolutionFitAgainstRepoGate	方案必须说明复用点、消费者、变更面、回滚和保持现状成本，避免凭空设计	reusePoint、consumer、rollback、statusQuoCost
ControlPlaneAdviceInventoryGate	控制面/复审分级/Gate 体系/规范如何改等建议路径，在宣称最优或可实施前必须对 source-root 做 ExistingCapabilityInventory；禁止仅用 user-global 镜像或对话记忆；与 analyze-default 同名门禁同向（PI-176 / PF-181）	inventory 表、reusePoint、gap、禁平行声明
UniqueRecommendationBeforeConfirmGate	多方案比较收敛后只能有一个推荐方案或一个明确组合推荐；任何用户须决策的路径建议（含完成态下一步）均适用	recommended=1、alternatives、reason
NoPreferenceMenuAfterConvergenceGate	已由证据收敛且用户授予 auto 时，不再要求用户选择无意义偏好菜单	auto evidence、decisionOwner
UniqueNextStepRecommendationGate	完成态 free-text「下一步/后续建议」仅 1 条主动作；禁止「或/或者」并列双可执行路径（PF-172）	single action、no or-fork、optional 不推荐 block

执行步骤

1. 判断产物类型和目标受众：用户、维护者、调用方、审核人或发布方。
2. 选择角色基线：技术专家、资深架构师、领域专家或用户文档作者。
3. 先反查项目和框架：已有 helper、middleware、plugin、types、schema、runtime dispatcher、配置系统、文档约定和官方 API。 3a. 若任务为控制面/复审等级/Gate 设计建议或「能否按 X 拆体系」：先执行 ControlPlaneAdviceInventoryGate（source-root inventory），再给推荐路径；未 inventory 不得写已验证最优。
4. 给出生产推荐路径：职责边界、使用方式、扩展点、失败处理、验证路线和维护成本。
5. 再标注非主路径：fixture / mock / demo / legacy / compat 的用途、风险和禁止外推范围。
6. 对容易误导的示例追加反模式对比：错误写法、为何不推荐、正确替代、如何迁移。
7. 建立 ExpertEvidenceMatrixGate：每个关键判断绑定至少一种事实证据；无法验证时写 unknown / blocked / N/A + skipReason。
8. 报告或复审中发现产物仍像初级解释时，先执行 ReviewEscapeRecordGate，说明此前清单为什么没有覆盖专业度维度，再补本 Skill 重跑。

输出字段

## ExpertOutputQualityGate

| 字段 | 内容 |
|------|------|
| roleBaseline | 技术专家 / 资深架构师 / 领域专家 / 用户文档作者 / N/A |
| productionRecommendedPath | 生产推荐写法、职责边界和使用入口 |
| frameworkNativeCapability | 框架 / SDK / 项目既有能力证据；无则写 N/A + skipReason |
| fixtureBoundary | fixture / mock / demo / hard-coded sample 的用途与禁止外推范围 |
| exampleArchitectureFitness | 示例是否符合推荐架构；不符合时给替代示例 |
| antiPatternContrast | 错误写法、风险、替代方案；不需要时写 N/A |
| evidenceMatrix | 判断 -> 代码/类型/官方文档/测试/运行时/用户路径证据 |
| operationExplanation | `OperationExplanationContractV1`，不涉及用户/维护者操作时写 N/A + skipReason |
| codeTruthEvidence | `CodeTruthEvidenceMatrixGate`，绑定 repo path / symbol / currentBehavior / negativeProbe / gap |
| solutionFitAndRecommendation | `SolutionFitAgainstRepoGate` + `UniqueRecommendationBeforeConfirmGate` / `NoPreferenceMenuAfterConvergenceGate` / `UniqueNextStepRecommendationGate` |
| controlPlaneAdviceInventory | 触发时：ExistingCapabilityInventory 摘要；未触发写 N/A + skipReason |

常见修正

初级产物问题	专家型改法
“fixture 每个 route 都重复 middlewares，所以说明可用”	说明 fixture 只证明底层 RouteOptions.auth 存在；生产推荐使用认证插件集中注册、资源 mapper 或 route group / preset helper，route 只保留最小业务声明
示例把硬编码单例当主路径	标为 smoke / demo，并给真实批量、配置化或生命周期完整的主路径
文档只解释内部实现字段	先写用户任务、配置选择、成功/失败路径，再把内部字段放到 developer / maintainer 章节
报告只说“已验证通过”	写生产入口命令、输入、输出、exitCode、代码落点和残余风险（MeasuredVerificationStandard）
用隔离脚本 40 错宣称 V84/core 红	先跑 npm run test:core；隔离须复用 createCanonicalAwareReader 才可谈 V# 等价
手写框架已有能力	先列框架原生能力和项目既有 helper；仅在有缺口时新增抽象

与其他 Skill 的关系

• dev-docs / user-manual-authoring：文档和用户手册需要本 Skill 检查示例、推荐路径和内部实现边界。
• dev-plan-review：CP2 中涉及架构、框架能力、示例或 fixture 时，本 Skill 是 PR-2 阻断项。
• audit-project / audit-document / audit-readme / audit-user-manual：审查代码、文档、README 或用户手册时叠加本 Skill。
• test-router：把 expertOutputQuality 写入 TestRoute，并选择源码反查、类型检查、官方文档、运行时探针或人工证据。
• report：报告必须列 ExpertOutputQualityGate 结果；若未触发写 N/A + skipReason。

禁止

• 禁止把 fixture、mock、硬编码样例、单例 smoke 或重复声明当成生产推荐路径。
• 禁止只说“不推荐”但不给框架原生能力、项目既有能力或推荐替代。
• 禁止只按审查报告、历史记忆或截图文字下结论；关键判断必须有本地或官方证据。
• 禁止为了“显得专业”过度设计；新增抽象仍需真实消费者、维护收益和项目边界依据。