agentleFS
Sunnyshinnny776Sunnyshinnny776/pm-agentic-cookbook/skills/journey-audit/SKILL.md

journey-audit

Skill4 starsChanged 35 days agoApache-2.0View on GitHub

为产品原型生成基于验收标准与 PRD 的人工 E2E 覆盖清单(阶段 A),或对录制旅程给出一致性、覆盖度与盲区结论(阶段 B)。当前目标或已采用工作流需要对应阶段产出时使用。明确需要则执行;阶段或交付目标有实质歧义时先问;明确不需要则不调用。生成清单不自动启动旅程审计。

The file

Files
SKILL.md

journey-audit

PM Agentic Cookbook 六阶段流程中阶段五:测试(Test) 的运行时审计层。test-authoring(按宿主测试规范所定的测试栈)负责单元/集成/组件层;本 skill 负责宿主测试规范(宿主契约 host.specMap 的 testing 角色)推迟到组件测试之外的 E2E 跨页面流程层,在真实运行的应用实例上以一次完整用户旅程为单位验证跨页面业务流程逻辑与已确认验收标准、PRD细化及宿主规则的一致性。

本 skill 为两段式,共享同一份「人工 E2E 覆盖清单」artifact:

  • 阶段A · 覆盖清单生成(人工测试前):从已确认验收标准及 PRD/spec 细化的适用范围派生出"应人工 E2E 覆盖什么",驱动人工测试。
  • 阶段B · 旅程审计(人工测试后):对录制旅程逐维度核验,并对照阶段A清单计算覆盖度。

按下方调用判断选择所需阶段;阶段 A 可由作者执行,阶段 B 的独立性要求不反向启动任一阶段。

调用判断

先判断本 skill 的产出是否属于用户当前目标或已采用工作流的当前步骤。Allow:明确需要则执行,不重复确认。Ask:上下文支持需要与不需要本产出的两种合理解释,且会改变交付范围时,简述差别和建议并等待答复。Deny:明确不需要或用户排除时,完成原任务与作者检查,不调用、不额外询问。不能因可能有帮助、读过材料或自行增加报告而建立调用依据。

已确认目标在范围不变时持续有效;明确需要但缺输入时只补输入。Ask 未获答复不执行,Deny 不拒绝原任务。这是行为约定,无运行时权限拦截。以下隔离、取证与报告要求仅在所需阶段获 Allow 后适用;读取本文件不等于启动流程。

宿主路径

本 skill 读宿主的 spec、往宿主的模块目录写产物,路径一律取自宿主契约(宿主根目录 cookbook.config.json 的 host 一节),不写死、不从目录内容反推:

  • 模块目录:host.moduleDocs 中的 <module> 换成被审模块的目录名。
  • 覆盖清单:<模块目录>/<host.testsDir>/<前缀>_e2e_coverage_manifest.md。
  • 审计报告:<模块目录>/<host.processRecordsDir>/<前缀>_e2e_audit_report.md。
  • 前缀:由调用方随模块名一起给出(模块目录名与文件名前缀可能不同);未给出时问用户,不从目录内既有文件反推。
  • spec:按角色从 host.specMap 取——测试规范是 testing 角色,UI/UX spec 是 ui-ux 角色,集成 spec 是 integration 角色。

上述字段任一未声明时,停下请用户指明,不猜路径。ui-ux 角色未声明而原型是按 ui-generator 的默认 UI/UX 规则生成的(其交付说明写明了规则来源与位置),请调用方把那份默认规则文件作为 UI/UX 规则交给本 skill;给出后以它为 UI/UX 预言,并在产出中写明规则来源。

模式与输入

阶段A(plan)输入

  • PRD/spec 细化:被覆盖模块的 PRD、状态机、权限矩阵、流程图、集成 spec、UI/UX spec,与已确认验收标准共同界定覆盖范围。
  • 已确认验收标准清单:提供名称、路径与版本;旅程引用清单名称加编号,不复制主表。
  • 需求范围与版本:最终确认范围及关联模型/PRD;跨范围集成出口单列,子范围通过不能推出共同出口通过。
  • test-authoring 已覆盖面:用于从全集中扣除。来源 = 宿主测试文件头注释/describe 标注的 PRD 章节 + 模块测试报告「追溯 PRD」列(机制见 coverage-manifest ②)。
  • 调用方给出被覆盖的模块。

阶段B(run)输入

  • 被审模块与文件名前缀:由调用方给出(见「宿主路径」);未给出时问用户,不从快照里的导航节点推断模块。
  • 逐步语义快照(磁盘文件名 User_Journey_<timestamp>.steps.json,下文统称 journey_steps.json):录制器对每次交互(点击/输入/导航)产出的结构化快照(当前路由/节点、生效角色、状态语义、当前可见且可用操作、关键数据字段)。schema 与命名见 capture-format。
  • 可回放脚本(同名 User_Journey_<timestamp>.js,统称 journey.js,codegen 产物):按需回放复现。
  • 阶段A 覆盖清单:作为覆盖度 diff 的基准。
  • 共同预言:已确认验收标准清单的名称/路径/版本及适用范围,关联PRD细化与宿主规则;从原始来源加载,不把阶段A清单当作规则本体。

录制产物的位置由调用方给出(录制目录或某一组 *.steps.json 的路径)。录制产物含明文输入,属临时产物,不应纳入版本管理。调用方没有给出时停下请用户指明,不按某个约定目录自行扫描。须长期留存的旅程,脱敏后 promote 到 <模块目录>/<host.testsDir>/。

调用方随调用给出的参数,优先作为输入源。

核心原则

  1. 共同预言(oracle):覆盖范围与每步期望取自已确认验收标准、PRD细化与宿主规则,不取自实现现状。来源冲突时报告冲突并交用户裁定,不自行择一。标准已明确而细化不足时保留标准依据并记录上游细化缺口;可由标准和快照直接判定的项仍核验,无法判定的细节不推测。所有来源均未规定的点标「口径待确认」,不下结论。偏差优先判定为真实发现。
  2. 可自评,不自我宣告通过:如实给出覆盖清单、逐步符合/偏差判定与 P 分级,不输出"流程通过/可推进"的自我背书;通过与否由用户裁定。
  3. 覆盖度诚实:① 覆盖清单须扣除单测已覆盖项与纯视觉盲区,标明取舍依据;② 审计报告须显式区分已判定维度、需人工视觉复核维度、未覆盖(未审计)项,不得将"未检出异常"等同"无缺陷"。盲区见 coverage-boundary。
  4. 以旅程为审计单位:使单次旅程的流程逻辑偏差可见、可定位、可裁定,不以维度数量为指标。

执行者与上下文隔离

本 skill 属审计类。若当前 Agent 是被审原型/PRD 的作者,阶段B(run)必须委派独立子代理执行:作者上下文携带对自身实现的辩护,自审必然偷懒。派发规则见本 skill 所在 cookbook 的 Agent 执行协议(<cookbook>/process/agent-execution-protocol.md)3(冷启动必给:产物路径、oracle 路径、输出位置、完成标准);单独安装、取不到该协议时,按括号里的四项派发,另写明对抗式立场(任务是找出偏差,不采信作者的自述)与中断落盘(边审边把已完成部分写进报告文件),并在报告中注明未按协议全文派发。阶段A(plan)从 PRD 派生清单,无作者偏差,可由主 Agent 执行。两阶段之间的"人工照单测试"槽位亦可由走查子代理执行,派发 prompt 见同一协议 4(照单 E2E 走查子代理,协议给出 cookbook 顶层的走查 prompt 模板);取不到时,派发 prompt 至少写明被测原型的访问方式、阶段A覆盖清单的路径、录制产物的存放位置,并要求逐条照单走查、只记录不修复;此时阶段B的审计者须独立于走查执行者。主 Agent 只回收并原样转呈子代理报告,不得改写其结论。

阶段B与照单 E2E 走查始终为 report-only,只写指定审计/走查报告和项目约定的原始录制产物;不得修改原型源码、PRD、spec 或测试。复审只核销派发清单中的原问题;新增偏差独立编号并写入报告。已获任务授权的作者按宿主规则处理范围内修复与规定复核,无需重复确认;业务取舍、修改 Oracle、扩范围或增加未约定的走查轮次交用户裁定。无宿主规则时遵循调用方已有授权;授权不足才询问。

执行流程

模式分派(先判定走哪个阶段)

依调用方给出的参数与意图选择,只执行其一:

  • 阶段A(plan):调用参数含 plan,或意图为"生成覆盖清单 / 我该测哪些环节 / 测试前出 list"。
  • 阶段B(run):调用参数含 run 或指向 *.steps.json 路径,或意图为"审计旅程 / 检查这次流程是否符合 PRD"。
  • 无法判定时:调用方给出了录制产物则倾向 run,没有则倾向 plan;仍不确定时直接问用户走 plan 还是 run,不擅自假设。

阶段A · 覆盖清单生成

严格按序。

  1. 读取范围内已确认清单及共同预言;清单缺漏/待确认、来源冲突或缺少可执行细化时,阶段A暂停受影响覆盖规划,保留标准与缺口,回到上游修订并获确认;阶段B仅报告上游缺口,由获授权的作者回改,不改变report-only边界,也不抹去已有依据可判定的项。加载可用PRD/spec细化(节点 × 角色 × 分支 × 关键数据条件);加载 test-authoring 已覆盖面。领域由调用方显式给出:指定了领域就加载 references/providers/<domain>/ 下的 oracle-map 与 baseline(阶段 B 另加载同目录的 capture-anchors,定位快照字段时使用);未指定则只用域无关的维度引擎 audit-dimensions,并在产出中声明"未加载领域补充规则"。本文件不写死任何领域的路径。
  2. 计算覆盖范围(减法):

    人工 E2E 覆盖清单 = 已确认标准及 PRD/spec 细化的适用范围
                      − test-authoring(单测)已覆盖项
                      − 纯视觉盲区(转入"需人工视觉复核",不进旅程清单)
  3. 按 业务关键度 × 可测性 排序去重,得到可执行的优先级清单(非笛卡尔积全排列)。
  4. 产出覆盖清单文档,每条旅程包含覆盖的验收标准(清单名称加编号),并逐标准对照已计划、已由测试覆盖、转人工视觉核验与未覆盖及原因;从清单实际条目核对,不把命中同一PRD章节算作全部已覆盖。生成规约与文档结构见 coverage-manifest。

阶段B · 旅程审计

严格按序,不跳步。

  1. 定位产物(调用方给出的是目录时,按文件名时间戳取其中最新一组 User_Journey_*.steps.json + 同名 .js;未给出时停下请用户指明),解析该 *.steps.json,重建本次旅程的 节点序列 × 生效角色 × 状态序列 × 操作集。
    • 前置序章裁剪:录制器通常自浏览器启动即采集,会把登录、跨模块漫游、被审旅程首个相关节点之前的准备步骤一并录入。重建时先识别「前置序章」= 旅程逻辑起点之前的步骤(逻辑起点 = 命中阶段A清单条目 涉及节点/前置数据 的首个被审模块节点),将其单列为「前置序章(不计入逐维度审计与覆盖度)」,只对逻辑起点之后的步骤做核验。无法判定逻辑起点时,标「旅程边界待确认」交用户,不擅自从首步开审。
  2. 加载共同预言并逐维度核验实际快照,每条结论标注追溯的 清单名称加标准编号、PRD规则/章节或宿主规则 + 快照证据(步骤序号/字段)。维度清单域无关:audit-dimensions;所加载领域 Provider 的 baseline 与 oracle-map 提供细化定位,不能覆盖原始来源或排除已确认标准。未加载 Provider 时仍核验可由标准/PRD/spec及维度引擎直接判定的部分,并声明未加载的领域细化缺口。
  3. 读取被审旅程所属模块的阶段A覆盖清单(落点见「宿主路径」)做覆盖度 diff:已覆盖 vs 计划覆盖,列出未覆盖(未审计)项,定位到清单条目;清单缺失时标「阶段A 清单缺失,覆盖度不可计算」,不静默跳过。
  4. 标注覆盖边界:已由语义快照判定的维度 vs 落入视觉/时序盲区需人工复核的项(定位到步骤)。加载:coverage-boundary。
  5. 产出审计报告并移交裁定(见输出规范)。累加模式:若被审模块已存在审计报告(落点见「宿主路径」),不覆盖而是追加合并——把本旅程的发现去重并入偏差/观察清单(沿用既有编号续号),并重算累计覆盖度 diff(本次 + 历次已审旅程 vs 阶段A清单);在报告「被审旅程」处登记本次旅程文件并保留历史旅程列表。无既有报告则新建。

输出规范

  • 阶段A 覆盖清单(按 coverage-manifest 结构,按「宿主路径」落盘,作为两阶段握手锚点):每条含 旅程编号、覆盖的验收标准(清单名称加编号)、涉及节点、角色、前置数据、关键核验点(指向 audit-dimensions 维度 + 标准/PRD/spec条目)、优先级;并列"已由单测覆盖故排除"与"纯视觉盲区故转人工复核"两类取舍记录。
  • 阶段B 审计报告(套用 templates/tob_test_report.md,取不到时按下列各段自行组织并在报告中注明"未套用模板";按「宿主路径」落盘到过程记录目录(不与覆盖清单等结果文件混放),单模块单份累计报告):
    • 被审旅程登记:本次旅程文件 + 历次已审旅程列表(累加模式下持续追加)。
    • 前置序章段:被裁剪、不计入审计的登录/准备步骤(定位到步骤区间),与被审旅程区分。
    • 符合/偏差汇总 + 偏差清单(P 分级 + 裁定列,跨旅程续号去重);偏差分类为「实现缺陷」或「上游规则/Mock 口径待确认」,各附具名标准/PRD/spec追溯、快照证据与定位(可映射时附 file:line)。上游细化缺口单列,不抹去标准已能支持的符合/偏差结论。
    • 累计覆盖度 diff 段:历次旅程累计 已覆盖 vs 阶段A计划覆盖,列未覆盖项。
    • 需人工视觉复核段:落入盲区、本 skill 未能判定的项。
  • 证据等级逐条标注:一份报告内若同时存在「本代理实机走查」与「据他人录制快照重建判定」的条目(接手中断的走查、复用历史产物、按快照做覆盖度补齐),必须逐条标注证据等级,并在报告开头声明两类条目的数量。二手判定不得表述为一手;快照信息不足以判定的点标「快照不可判定,建议补走」,不推测、不填充。

交接实际已走查路径、标准/实现版本、可定位步骤及视觉/时序/未覆盖边界供范围级台账消费;计划覆盖不算实跑,单元绿色不等于完整旅程成立,旧录制不证明改变后的语义。流程作者汇总,审计者只报告,用户明确验收;本skill不更新台账、标准或用户结论。

  • 累计报告的追加边界:同一模块的多轮报告共存于一个文件时,后续轮次只追加自己的顶层章节,不修改、稀释或改写既有章节与结论(既有章节是另一个独立执行者的产物)。追加后以 git diff --numstat 自查删除行数为 0。
  • 缺陷分级:P0 阻断核心流程或数据正确性;P1 关键规则偏离已确认标准或PRD/spec;P2 口径待确认/边界;P3 优化项。
  • 禁止:将"快照未检出异常"表述为"流程通过";或代用户下达通过结论。
  • 禁止:在阶段B或照单走查中直接修复任何发现,即使偏差可追溯到明确 oracle;修复由审计/走查之外、已获相应任务授权的 implementation Agent 执行;既有授权仍适用时无需重新授权。

停机条件

阶段A 完成:覆盖清单已落盘,每条旅程有具名验收引用、优先级与核验点,已确认标准的计划/排除/未覆盖状态有理由;"已由组件测试覆盖故排除"与"纯视觉盲区故转人工"两类取舍都有记录。

阶段B 完成:

  1. 本次全部旅程逐步核验完毕,偏差都有快照证据与定位
  2. 累计覆盖度对照与"需人工视觉复核"段已写
  3. 证据等级逐条标注;累计报告只追加了本轮章节

停下交用户:录制产物缺步或损坏,无法判定的步骤超过一半;共同预言存在冲突,或所有来源均不足以判定整条旅程。PRD细化不足时保留可由标准直接判定的项和上游缺口,不把整条旅程自动转为待确认。

不宣告"流程通过",不修复任何发现。

工作风格

  • 所有来源均未规定或存在冲突时标注「口径待确认」交用户,不自行假设;缺少PRD细化不撤销已确认标准。
  • 覆盖全集在工程上是优先级清单,非全排列;深度由用户裁定。
  • 维度清单与生成规约开放可扩展:增补 references/ 后用 scripts/build.py 重建 dist/。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.