This skill is the layer between "code changes complete → claiming done / submitting a PR"verification execution and evidence recording layer. It solves one core problem:compiles ≠ feature works。
It is responsible for actually running the applicable stages, observing the final state of the feature, and preserving stage facts;production-engineering-audit(PEA) is the sole arbiter of the completion
level. When machine-consumable layered evidence is needed, read
references/staged-receipt.md, use a deterministic converter to generate a staged receipt,
then hand it to PEA. Do not create another READY / RELEASED verdict within this Skill.
Direct lesson: after changing the reader worker loading,
typecheck/ build / lint / unit tests all passed, so "fixed" was claimed, but on the real device it crashed with "text layer unknown" (textLayerStatusstuck at unknown)—the compilation layer simply cannot catch runtime feature problems. The only solution for this kind of pitfall is e2e (feature verification) + real device。
Working principles
- Compilation layer first (1-4), then feature layer (5-6): the compilation layer is a prerequisite gate, butnot sufficient; the feature layer (e2e + real device) is the completion line.
- e2e/real-device failures must be recorded truthfully: if 5/6 do not pass, they cannot serve as passing evidence for the corresponding completion claim, no matter how clean 1-4 are; whether the completion level required by the project is reached is left to PEA to adjudicate per the project contract.
- Assert feature results, not "element exists": when teaching users to write e2e, assert "canvas pixels non-empty / textLayerStatus ≠ unknown / the panel really pops up after clicking", rather than "a canvas exists / a button exists" (to prevent fake rendering / false success).
- Bug fixes must add a reproduction test(regression convention): after fixing a bug, add an e2e/unit test that can reproduce that bug, to prevent regression.
- A hanging suite = not passed：
npm testnever exits (summary not printed / process does not exit) is treated as a P0 infrastructure defect; for the diagnostic playbook seereferences/lessons-from-practice.mdlesson 12; bypassing with a subset can only be a temporary state with a logged task—hanging masks real failures (lesson 11: on the day of the fix, 3 failures hidden for weeks were exposed). - Do not trust producers (worker/PM themselves) self-reporting PASS: run the actual commands, look at the actual output.
- Choose verification commands by project type: Tauri desktop / Web / service / Skill have different commands (see §project type branches).
8-stage verification
| # | Stage | Gate | Completion line | CI |
|---|---|---|---|---|
| 1 | Build (build / cargo check) | Stop on failure, do not continue | Prerequisite | ✅ Enters CI (PR blocking item) |
| 2 | Type checking (typecheck) | Key errors cleared to zero | Prerequisite | ✅ Enters CI (PR blocking item) |
| 3 | Lint（--max-warnings=0 + dependency cycles) |
Zero warnings + no dependency cycles | Prerequisite | ✅ Into CI (PR blocking item) |
| 4 | Unit tests (vitest layered) | Pass + coverage meets standard | Prerequisite | ✅ Into CI (PR blocking item) |
| 5 | e2e functional verification (Playwright) | Functional result assertions(not element existence) | Core completion line | ✅ Into CI (PR blocking item, critical) |
| 6 | Real-device verification (etv / build / staging) | Real runtime behavior | Core completion line | ⚠️ Usually run locally / on staging (CI hard to simulate real device, as needed) |
| 7 | Security scan (secrets / debug logs) | No leaks / no leftover console.log | Prerequisite | ✅ Into CI (PR blocking item) |
| 8 | Diff review (scope / out-of-bounds) | Changes compliant, no forbidden files | Prerequisite | ✅ Into CI (PR blocking item) |
CI column description: ✅ = recommended to run automatically in CI, failure blocks PR merge; ⚠️ = real-device environments are generally hard for CI to simulate, run locally or in an independent staging pipeline. When running manually locally, run all 8 stages; in CI run 1-5 + 7-8 (real device missing).
Stages 1-4: Compilation layer (prerequisite gate, not sufficient)
# 1 构建
npm run build 2>&1 | tail -20 # 前端
cd src-tauri && cargo check 2>&1 | tail # Tauri Rust
# 2 类型检查
npm run typecheck 2>&1 | tail
# 3 Lint（严格：零警告 + 依赖环）
npm run lint -- --max-warnings=0 2>&1 | tail
npx depcruise --config .dependency-cruiser.cjs src 2>&1 | tail # 依赖环（如有）
# 4 单元测试（分层）
npm test 2>&1 | tail -50 # vitest（unit + integration + dom 分层）
Gate: any failure → stop, fix before continuing. But passing all 4 layers ≠ functionality usable。
Stage 5: e2e functional verification (core completion line)
This is the only solution to "compiles ≠ functionality usable". Use Playwright (or equivalent) to drive the application, and assertfunctional results。
npm run test:e2e -- tests/e2e/reader-renders.test.ts # FaroPDF 实际路径示例
# 或项目既有：npm run verify:reader-e2e（chromium 真 Worker 功能门禁）
Assertion depth—not just "element existence", assert functional results (see references/assertion-depth.md）。
Gate fact: if e2e fails, record failed, do not treat this stage as behavior-complete evidence; PEA determines whether the current
claim is blocked.
Stage 6: Real-device verification (core completion line)
dev server e2e is not enough—real runtime (Tauri WKWebView / Web build artifacts / service staging) behavior may differ.
| Project type | Real-device verification |
|---|---|
| Tauri desktop | npm run tauri build real-device artifacts (or etv:WEBKIT_INSPECTOR_SERVER + tauri dev real-device DOM + screenshot) |
| Web | npm run build + vite preview(build artifacts, not dev server) |
| Service | staging environment real requests |
Stage pass conditions: real-device behavior is consistent with dev e2e; prod-only issues (worker/protocol/path) must be caught on real device.
Stages 7-8: Security + Diff (prerequisite)
# 7 安全
grep -rnE "sk-|api_key|password|token" --include="*.ts" --include="*.rs" src/ src-tauri/ 2>/dev/null | grep -viE "test|fixture|env|placeholder" | head
grep -rn "console.log" --include="*.ts" --include="*.tsx" src/ 2>/dev/null | head
# 8 Diff 审查
git diff --stat
git diff HEAD~1 --name-only # 逐文件审：非预期变更 / 缺失错误处理 / forbidden 文件
Project type branches (select verification commands by project)
Tauri desktop
npm run build && cd src-tauri && cargo check # 1 构建
npm run typecheck # 2 类型
npm run lint # 3 lint
npm test # 4 单测
npm run test:e2e # 5 e2e（打开 PDF 渲染 + textLayerStatus 断言；jsdom 层）
npm run verify:reader-e2e # 5+ chromium 真 Worker 门禁（dev server 自起自灭）
npm run verify:prod-render # 5+ 产物层门禁（vite preview build 产物 + 真实 UI + Retina DPR=2）
# 6 真机：npm run tauri build 产物实机 / etv（npm run etv:dev + etv:run，WKWebView 真机 DOM + 截图）
# ⚠ 桌面 WebView 四层验证盲区（引擎代差/DPR/产物嵌入/dev≠打包）见教训 13：
# chromium 全绿 ≠ WKWebView 过；真机 console（构建戳确认版本）是唯一决定性证据
For real-device verification practices see references/e2e-practice.md(Tauri etv section).
Web
npm run build && npm run typecheck && npm run lint && npm test # 1-4
npm run test:e2e # 5 Playwright（CI 也跑）
# 6 真机：npm run build + vite preview（build 产物）
Service
npm run build && npm run typecheck && npm run lint # 1-3
npm test # 4 unit + integration
# 5 integration test（HTTP 请求断言响应）
# 6 真机：staging 环境真实请求
Skill
Reference skill-lint(existing Skill creation quality review). This skill does not duplicate skill-lint's responsibilities.
Trigger timing
- After completing a feature or major code changes
- Before creating a PR(hard gate for PR merge)
- After refactoring
- Before claiming "finished", "behavior-complete", or "done"(first produce stage facts, then let PEA adjudicate the completion level)
- After a bug fix (+ newly added reproduction test)
- Before release / delivery wrap-up, before "handing over to the user" the NOT_VERIFIED list— first close out layer by layer (see §NOT_VERIFIED layered close-out)
Continuous mode: execute every 15 minutes in a long session or after a major change (mental checkpoints: after finishing a function / after finishing a component / before switching tasks).
Local verification vs CI gate (must be clear)
You can do complete verification without GitHub Actions. The 8 stages of this skill are essentially "a set of commands to run before the code claims completion + judgment criteria"; where it runs and who runs it are independent:
- Local verification: you (or an AI agent) manually run
build → typecheck → lint → test → test:e2e, look at the actual output and record stage facts. Immediate and flexible, butrelies on self-discipline— prone to "it compiled, so it's fixed" (exactly the pit this skill aims to prevent). - CI gate(GitHub Actions / GitLab CI / Gitea / Jenkins, etc.): put thesame set of commandsinto the pipeline, run automatically on push / opening a PR, and on failureblock the merge. It does not change "what is verified", it just turns the gate intoan objective enforcement— code that does not pass the gate cannot be merged.
Key insight：
- CI is not "another kind of verification", it isthe automation vehicle for the same set of verification. If it passes locally, it can pass in CI; if you skip stages locally, CI will catch it back.
- The platform is not limited to GitHub Actions. Options: GitHub Actions, GitLab CI, Gitea Actions, Jenkins; locally you can also use
act(run GitHub Actions locally),lefthook/husky's pre-push hook to run automatically before committing. - This skill can be used without CI— as long as before claiming "fixed / opening a PR", you run the applicable stages locally, save evidence and hand it to PEA for adjudication. CI is a reinforcement so that "the team doesn't have to worry about someone skipping the gate"; it is not a prerequisite.
- Real device (stage 6) is generally hard to simulate in CI: Tauri WKWebView, build artifact behavior, real staging requests usually go local or in a separate staging pipeline. CI runs 1-5 + 7-8; the real-device gap must have its reason recorded in the "6 real device" column of the verification report (NOT_RUN needs sufficient justification).
Implementation suggestion: first get the 8 stages running smoothly locally and become familiar with the stage reports; then move it into CI (see
references/e2e-practice.md's "CI gate" generic template). The facts of the same stage locally and in CI should be consistent; on conflict, keep evidence and investigate environment differences; do not manually override a red light.
Local development: which verifications are necessary (minimum checklist by scenario)
The 8 stages do not all need to be done personally every time—the compilation layer (1-4) is forced on you by the toolchain,what is truly easy to miss and most worth remembering is the functional layer (5-6), because "it compiled ≠ the feature works". Take the minimum necessary set by scenario:
Daily bug fixing / feature writing (in the local loop)
1 构建 → 2 类型 → 4 单测（改了逻辑就跑）→ 5 e2e（宣称修好前必跑）
- 1-2 run them along the way (build / typecheck pass in one go).
- 4 unit tests: mandatory for pure logic changes; can be skipped if only styles are changed.
- 5 e2e is the soul of this checklist— Before declaring "fixed," you must run it; assert that the feature actually appears (pixels non-empty / textLayerStatus ≠ unknown). This is the only solution to pitfalls that the compile layer cannot catch.
Preparing to submit a PR / claim "fixed"
日常清单 + 6 真机（至少 build 产物跑一遍）+ 7 安全（grep 自查）+ 8 Diff（看 git diff）
- 6 Real device: dev runs fine, but the build artifact / real device may crash (worker / path / protocol differences).
- 7 Security: grep for secrets / console.log, or hand it to CI.
- 8 Diff: manually review git diff, confirm only what should have been changed was changed, no overreach / accidental deletion / forbidden files included.
If it can be automated, don't rely on remembering to run it manually (pre-push hook / CI block)
- 3 Lint：
husky/lefthookpre-push runs automatically, or CI runs it. - 7 Security scan: running in CI is more reliable, don't rely on self-discipline.
Key insight
- What you must personally do locally: 1-2-4 confirm the code level is OK + 5 e2e confirms the feature is actually usable。
- To add before submitting the PR: 6 real device + 8 review diff.
- If it can be automated, don't do it manually: 3 lint, 7 security.
- The minimum bar is not 1-4: Before you reach the step of claiming "done," 5 (and 6 in that scenario) must pass. All of 1-4 passing ≠ you can claim it's fixed.
Real lesson: after modifying the worker, typecheck / build / lint / unit tests all passed, but on the real device
textLayerStatusit hung on unknown and crashed—proving that all of 1-4 passing ≠ the feature is usable; if 5/6 don't pass, it's not fixed.
NOT_VERIFIED layered closure (release / delivery wrap-up)
After a feature is marked NOT_VERIFIED,at wrap-up it is forbidden to hand off the entire batch to the user—first bisect item by item:
| Category | Criterion | Action |
|---|---|---|
| Web layer verifiable | The feature surface exists in the browser DOM: UI rendering / interaction / localStorage persistence / clipboard (chromium grant permission can assert real content) | Agent Write a Playwright spec on the spot to verify, promote it to a regression e2e (into CI), and narrow the NOT_VERIFIED scope to what actually remains |
| Truly requires a real device | Depends on OS / Tauri runtime / webview-specific behavior: system API registration,invoke backend link, WKWebView look and feel |
Keep NOT_VERIFIED,precise to the remaining granularity( "only WKWebView clipboard writing," not the entire feature) |
- Self-check question: "In this checklist, how many items did I not run through Playwright, rather than truly being unable to verify?"
- For details and cases, see
references/lessons-from-practice.mdLesson 10; for className→CSS real rendering assertions, seereferences/assertion-depth.md"Visual / CSS classes".
Final output: phase report
| 阶段 | 结果 |
|-------------|-------------------------------|
| 1 构建 | PASS / FAIL |
| 2 类型 | PASS / FAIL (X errors) |
| 3 Lint | PASS / FAIL (X warnings) |
| 4 单测 | PASS / FAIL (X/Y, Z% cov) |
| 5 e2e 功能 | PASS / FAIL (X specs) | ← 硬门禁
| 6 真机 | PASS / FAIL / NOT_RUN(记原因) | ← 硬门禁
| 7 安全 | PASS / FAIL (X issues) |
| 8 Diff | X files, 范围合规/越界 |
| CI 门禁 | 1-5+7-8 全绿 / 有 job 红（阻断说明） |
Tables are suitable for humans to read, but must not attach a READY / RELEASED determined by this Skill itself. When machine consumption is needed, write the same batch of real phase
facts as verification-gate-stage-report/v1, convert according to
references/staged-receipt.md , and then PEA decides based on target, consumer,
candidate commit, and the project's minimum level. Failed phases must likewise enter the receipt; they must not be omitted just to generate a green light.
Definition of done (implementation)
Claiming a code change is "done" must:
- 1-4 compile layer all pass (prerequisite).
- 5 e2e feature verification passes(core).
- 6 real-device verified(core; desktop/Web/service by type).
- 7-8 security + Diff compliance.
- Bug fixadd reproduction test(regression).
- Output complete phase facts and in-repo evidence, and hand completion claims to PEA for adjudication.
e2e/real device failure = corresponding phase failure: do not disguise a failed phase as passing or omit it; whether to block commit, merge, or release is determined by PEA in combination with project configuration and claim level.
Dependencies
System dependencies
| Dependency | Installation method |
|---|---|
| node / npm | Bundled with the project |
| rust / cargo (Tauri project) | macOS: brew install rust |
Project dependencies (by type)
| Project type | Dependency | Purpose |
|---|---|---|
| General | vitest / eslint / tsc |
Unit tests / lint / types |
| General | playwright |
e2e functional verification |
| Tauri desktop | @tauri-apps/cli |
tauri build / dev real device |
| General (optional) | dependency-cruiser |
Dependency cycle detection (phase 3) |
Reference documents (references/; read as needed)
references/eight-phases-rationale.md：Want to understand "why 8 phases, and why compiling doesn't mean it works"— what each phase proves/does not prove, what e2e + real device fills in as blind spots, and counterexamples. Corresponds to §8 Phase Verification and §Local Development: which verifications are necessary.references/assertion-depth.md：When writing e2e— assert functional results vs only asserting that elements exist (to prevent fake rendering/false success), with four categories of cases: rendering/state/interaction/API. Corresponds to §Phase 5.references/e2e-practice.md：Implementing e2e / real device / CI— Playwright spec writing, fixture matrix, general CI template (platform-agnostic, not limited to GitHub Actions), Tauri etv real device. Corresponds to §Phase 5/6 and §Local vs CI Gates.references/test-pyramid.md：Organizing unit tests / verify scripts / regression conventions— vitest layering, build-embedded verify, bug fixes must add reproduction tests, strict lint. Corresponds to §Phase 3/4.references/lessons-from-practice.md：Pitfalls encountered while running the skill— pre-existing failure determination, missing e2e, Tauri invoke limitations, quick mode vs full mode, sources of real-device evidence, etc., providing continuous feedback. Corresponds to "Quick Mode" in §Local Development Checklist and the boundaries of §Phase 4/5/6.references/staged-receipt.md：After the phase has actually been executed— input contract, evidence paths, HEAD binding, conversion commands, and PEA consumption boundaries. Corresponds to §Final Output.
Related Skills
| Dimension | verification-gate | skill-lint | production-engineering-audit |
|---|---|---|---|
| Positioning | Layered verification execution and fact recording | Quality review after Skill creation/modification | Structural waste and completion claim adjudication |
| Object | Real phases of Tauri/Web/service/Skill | The Skill itself (SKILL.md/references/contract) | Project configuration, hot paths, and completion evidence |
| Relationship | Produces staged receipts, does not adjudicate levels | Verifies Skill structural compliance | Consumes receipts, adjudicates the upper limit of evidence support |
Code projects use the verification-gate execution phase, and Skills use skill-lint to review structure; when changing a Skill's code scripts, both apply. When preparing to claim "fixed / completed / ready to release", then hand the staged receipt to production-engineering-audit; the three do not substitute for each other.