Pre-Merge Checklist

合并前检查清单

When to Use

使用场景

Activate this skill when:

Reviewing a pull request before approving
Preparing your own PR for merge
Verifying that all automated checks pass before merging
Auditing a PR that has been approved but not yet merged
Running a final validation pass after addressing review feedback

Output: Write results to

pre-merge-report.md

with pass/fail status for each check and blocking issues.

Do NOT use this skill for:

In-depth security review (use
```
code-review-security
```
)

Writing implementation code (use

python-backend-expert

or

react-frontend-expert

)

Architecture decisions (use
```
system-architecture
```
)
E2E test creation (use
```
e2e-testing
```
)

在以下场景启用此技能：

批准前审查拉取请求（PR）
准备自己的PR以进行合并
合并前验证所有自动化检查是否通过
审计已批准但尚未合并的PR
处理审查反馈后执行最终验证

输出结果： 将每个检查的通过/失败状态以及阻塞问题写入

pre-merge-report.md

文件。

请勿在以下场景使用此技能：

深度安全审查（请使用
```
code-review-security
```
）

编写实现代码（请使用

python-backend-expert

或

react-frontend-expert

）

架构决策（请使用
```
system-architecture
```
）
端到端（E2E）测试创建（请使用
```
e2e-testing
```
）

Instructions

操作说明

Automated Checks (Ordered)

自动化检查（按顺序）

Run automated checks in this order. Each check must pass before proceeding to the next. Use

scripts/run-all-checks.sh

to execute all checks at once.

按以下顺序运行自动化检查。每项检查必须通过后才能进行下一项。可使用

scripts/run-all-checks.sh

一次性执行所有检查。

1. Linting and Formatting

1. 代码规范与格式检查

Python (ruff):

bash

undefined

Python（ruff）：

bash

undefined

Check linting

ruff check app/ tests/

Check formatting

ruff format --check app/ tests/

Auto-fix (if needed before commit)

ruff check --fix app/ tests/ ruff format app/ tests/


**TypeScript/React (eslint + prettier):**
```bash

ruff check --fix app/ tests/ ruff format app/ tests/


**TypeScript/React（eslint + prettier）：**
```bash

Check linting

npx eslint 'src/**/*.{ts,tsx}' --max-warnings 0

Check formatting

npx prettier --check 'src/**/*.{ts,tsx}'

Auto-fix (if needed)

npx eslint 'src//*.{ts,tsx}' --fix npx prettier --write 'src//*.{ts,tsx}'


**Pass criteria:**
- Zero lint errors (warnings are tolerated only with justification)
- All files formatted consistently
- No `# noqa` or `eslint-disable` without a comment explaining why

npx eslint 'src//*.{ts,tsx}' --fix npx prettier --write 'src//*.{ts,tsx}'


**通过标准：**
- 无代码规范错误（仅在有合理理由时可容忍警告）
- 所有文件格式一致
- 无未附带解释注释的`# noqa`或`eslint-disable`指令

2. Type Checking

2. 类型检查

Python (mypy):

bash

mypy app/ --strict --no-error-summary

TypeScript:

bash

npx tsc --noEmit

Use

scripts/type-check.sh

to run both in sequence with report output.

Pass criteria:

Zero type errors in changed files
No new
```
type: ignore
```
or
```
@ts-ignore
```
without justification
Generic types used correctly (no
```
Any
```
leaks)

Python（mypy）：

bash

mypy app/ --strict --no-error-summary

TypeScript：

bash

npx tsc --noEmit

可使用

scripts/type-check.sh

按顺序运行两项检查并生成报告。

通过标准：

变更文件中无类型错误
无未附带理由的新增
```
type: ignore
```
或
```
@ts-ignore
```
指令
泛型类型使用正确（无
```
Any
```
类型泄漏）

3. Tests

3. 测试

Python:

bash

pytest tests/ -q --tb=short

React:

bash

npm test -- --run --reporter=verbose

Pass criteria:

All tests pass (zero failures)
No skipped tests without a linked issue/ticket
New code has corresponding tests

Python：

bash

pytest tests/ -q --tb=short

React：

bash

npm test -- --run --reporter=verbose

通过标准：

所有测试通过（零失败）
无未关联问题/工单的跳过测试
新增代码有对应的测试

4. Coverage

4. 测试覆盖率

Python:

bash

pytest --cov=app --cov-report=term-missing --cov-fail-under=80

React:

bash

npx vitest run --coverage --coverage.thresholds.lines=80

Pass criteria:

Overall coverage >= 80%
New code coverage >= 90%
No critical paths left uncovered (auth, payment, data mutation)

Python：

bash

pytest --cov=app --cov-report=term-missing --cov-fail-under=80

React：

bash

npx vitest run --coverage --coverage.thresholds.lines=80

通过标准：

整体覆盖率≥80%
新增代码覆盖率≥90%
无关键路径未覆盖（认证、支付、数据变更）

5. Security Scan

5. 安全扫描

bash

undefined

bash

undefined

Python dependencies

pip-audit --requirement requirements.txt

npm dependencies

npm audit --audit-level=high

Custom code scan (if code-review-security skill is available)

python scripts/security-scan.py --path app/ --output-dir ./security-results


**Pass criteria:**
- No critical or high severity vulnerability in dependencies
- No critical findings in code scan
- All new endpoints have authentication checks

---

python scripts/security-scan.py --path app/ --output-dir ./security-results


**通过标准：**
- 依赖项中无严重或高危漏洞
- 代码扫描中无严重问题
- 所有新增端点均有认证检查

---

Manual Review Checklist

手动审查清单

After automated checks pass, review the PR manually against these categories.

自动化检查通过后，对照以下类别手动审查PR。

Code Quality

代码质量

Naming: Variables, functions, and classes have clear, descriptive names
Functions: Each function does one thing; no function exceeds 50 lines
DRY: No duplicated logic that should be extracted into a shared function
Comments: Complex logic is documented; no commented-out code left in
Imports: No unused imports; imports are organized (stdlib, third-party, local)
Constants: No magic numbers or strings; use named constants or enums
Logging: New features have appropriate log statements at correct levels

命名规范： 变量、函数和类具有清晰、描述性的名称
函数设计： 每个函数仅负责单一功能；函数代码不超过50行
DRY原则： 无应提取为共享函数的重复逻辑
注释规范： 复杂逻辑有文档说明；无遗留的注释代码
导入规范： 无未使用的导入；导入按标准库、第三方库、本地代码分类组织
常量使用： 无魔法数字或字符串；使用命名常量或枚举
日志规范： 新增功能有适当级别的日志语句

Testing

测试

Coverage: New code has tests (unit and/or integration as appropriate)
Edge cases: Tests cover happy path, error paths, and boundary conditions
Test names: Test names describe the scenario and expected outcome
Test isolation: Tests do not depend on each other or on execution order
No flakiness: Tests do not use hardcoded delays or environment-specific paths
Factories: Test data uses factories, not hardcoded fixtures

覆盖率： 新增代码有对应的测试（单元测试和/或集成测试，按需选择）
边界场景： 测试覆盖正常路径、错误路径和边界条件
测试命名： 测试名称描述场景和预期结果
测试隔离： 测试之间无依赖，与执行顺序无关
无不稳定测试： 测试不使用硬编码延迟或环境特定路径
测试数据： 测试数据使用工厂模式，而非硬编码固定数据

Type Safety

类型安全

No
Any
: Return types and parameters are properly typed (no escape hatches)
Null safety: Optional values are handled (null checks, default values)
Schema validation: API inputs use Pydantic schemas (Python) or Zod (React)
Generic types: Collections use proper generics (
```
list[User]
```
, not
```
list
```
)

无
Any
类型：返回类型和参数均正确标注类型（无规避手段）
空值安全： 可选值已正确处理（空值检查、默认值）
Schema验证： API输入使用Pydantic Schema（Python）或Zod（React）
泛型类型： 集合使用正确的泛型（如
```
list[User]
```
，而非
```
list
```
）

Error Handling

错误处理

Graceful errors: All error paths return meaningful messages
HTTP status codes: Correct codes used (404 for not found, 409 for conflict, etc.)
Error boundaries: React components have error boundaries for async failures
Retry logic: External service calls have retry with backoff (where appropriate)
No silent failures: Caught exceptions are logged, not silently swallowed

优雅错误： 所有错误路径返回有意义的提示信息
HTTP状态码： 使用正确的状态码（如404表示资源不存在，409表示冲突等）
错误边界： React组件有处理异步失败的错误边界
重试逻辑： 外部服务调用有退避重试机制（按需使用）
无静默失败： 捕获的异常已记录日志，而非被静默忽略

Backwards Compatibility

向后兼容性

API contracts: No breaking changes to existing API response shapes
Database migrations: Migrations are reversible and non-destructive
Feature flags: Breaking changes are behind feature flags
Deprecation: Removed features have deprecation warnings in prior release
Configuration: No new required environment variables without documentation

API契约： 对现有API响应格式无破坏性变更
数据库迁移： 迁移可回滚且无破坏性
功能开关： 破坏性变更已置于功能开关之后
废弃处理： 移除的功能在之前版本中已添加废弃警告
配置： 无未附带文档的新增必填环境变量

Documentation

文档

API docs: New endpoints are documented (OpenAPI/Swagger via FastAPI)
README: Setup instructions updated if new dependencies or steps added
Migration notes: Database migration has a description comment
ADR: Significant architectural decisions documented (if applicable)

API文档： 新增端点已完成文档（通过FastAPI生成OpenAPI/Swagger）
README： 若新增依赖或步骤，已更新安装说明
迁移说明： 数据库迁移有描述性注释
ADR： 重大架构决策已文档化（如适用）

Performance

性能

N+1 queries: No N+1 database query patterns (use eager loading)
Pagination: List endpoints use cursor-based pagination
Indexes: New query patterns have supporting database indexes
Bundle size: No unnecessary large dependencies added to frontend

N+1查询： 无N+1数据库查询模式（使用预加载）
分页： 列表端点使用基于游标分页
索引： 新增查询模式有对应的数据库索引支持
包大小： 前端未添加不必要的大型依赖

Accessibility

无障碍性

Semantic HTML: Correct HTML elements used (button, nav, main, etc.)
ARIA labels: Interactive elements have accessible labels
Keyboard navigation: New UI elements are keyboard-accessible
Color contrast: Text meets WCAG 2.1 AA contrast requirements

Use

scripts/accessibility-check.sh

to run automated accessibility checks.

语义化HTML： 使用正确的HTML元素（button、nav、main等）
ARIA标签： 交互元素有可访问标签
键盘导航： 新增UI元素支持键盘导航
颜色对比度： 文本符合WCAG 2.1 AA对比度要求

可使用

scripts/accessibility-check.sh

运行自动化无障碍检查。

Failure Protocol

失败处理流程

When a check fails, follow this escalation path:

Automated check failure:

Fix the issue in the PR
Push the fix and re-run checks
Do not merge until all automated checks pass

Manual review finding:

Add a review comment with the finding
Request changes on the PR
Re-review after the author addresses feedback

Severity-based response:

Finding Type	Action	Can Override?
Lint/format error	Fix before merge	No
Type error	Fix before merge	No
Test failure	Fix before merge	No
Coverage below threshold	Add tests or justify	Yes, with tech lead approval
Security finding (critical/high)	Fix before merge	No
Security finding (medium/low)	Fix or create follow-up ticket	Yes, with ticket reference
Accessibility violation	Fix or create follow-up ticket	Yes, with justification
Performance concern	Discuss in PR, may defer	Yes, with tech lead approval

当检查失败时，遵循以下处理流程：

自动化检查失败：

在PR中修复问题
推送修复并重新运行检查
所有自动化检查通过前不得合并

手动审查发现问题：

添加审查注释说明问题
在PR上标记“请求变更”
作者处理反馈后重新审查

基于严重程度的响应：

问题类型	操作	是否可例外？
代码规范/格式错误	合并前修复	否
类型错误	合并前修复	否
测试失败	合并前修复	否
覆盖率低于阈值	添加测试或提供理由	是，需技术负责人批准
安全问题（严重/高危）	合并前修复	否
安全问题（中危/低危）	修复或创建后续工单	是，需关联工单
无障碍违规	修复或创建后续工单	是，需提供理由
性能问题	在PR中讨论，可延迟处理	是，需技术负责人批准

Override Process

例外审批流程

If a check must be overridden:

Document the reason in a PR comment explaining why the override is acceptable
Get explicit approval from a tech lead or senior engineer
Create a follow-up ticket to resolve the underlying issue
Add a code comment at the override point referencing the ticket

python

undefined

若必须跳过某项检查：

记录理由：在PR评论中说明为何例外是可接受的
获取明确批准：需技术负责人或资深工程师批准
创建后续工单：解决潜在问题
添加代码注释：在例外位置关联工单

python

undefined

OVERRIDE: Coverage below 80% for this module. See TICKET-1234.

Approved by @tech-lead on 2024-01-15.

Reason: Legacy code migration in progress; full coverage planned for Sprint 12.


Overrides are never acceptable for:
- Critical security vulnerabilities
- Broken tests
- Type errors that mask bugs


以下情况绝不允许例外：
- 严重安全漏洞
- 测试失败
- 隐藏bug的类型错误

Examples

示例

Running All Checks

运行所有检查

bash

undefined

bash

undefined

Run the full check suite

./scripts/run-all-checks.sh --output-dir ./check-results

Run only type checks

./scripts/type-check.sh --output-dir ./check-results

Run accessibility checks

./scripts/accessibility-check.sh --output-dir ./check-results

undefined

./scripts/accessibility-check.sh --output-dir ./check-results

undefined

Quick PR Review Workflow

快速PR审查流程

Pull the branch locally

Run

./scripts/run-all-checks.sh --output-dir ./pr-review

Review the automated results file
Walk through the manual checklist above
Leave review comments or approve

本地拉取分支

运行

./scripts/run-all-checks.sh --output-dir ./pr-review

查看自动化结果文件
对照上述手动审查清单检查
留下审查评论或批准

Output File

输出文件

Write results to

pre-merge-report.md

:

markdown

undefined

将结果写入

pre-merge-report.md

：

markdown

undefined

Pre-Merge Report: [PR Title]

Status: READY TO MERGE | BLOCKING ISSUES

Automated Checks

Check	Status	Details
Linting (ruff)	PASS	No issues
Type check (mypy)	PASS	No errors
Tests (pytest)	PASS	142 passed, 0 failed
Coverage	PASS	85% (threshold: 80%)
Frontend lint	PASS	No issues
Frontend types	PASS	No errors

Check	Status	Details
Linting (ruff)	PASS	No issues
Type check (mypy)	PASS	No errors
Tests (pytest)	PASS	142 passed, 0 failed
Coverage	PASS	85% (threshold: 80%)
Frontend lint	PASS	No issues
Frontend types	PASS	No errors

Manual Checks

Code follows project patterns
Tests cover new functionality
No breaking API changes
Documentation updated (BLOCKING)

Code follows project patterns
Tests cover new functionality
No breaking API changes
Documentation updated (BLOCKING)

Blocking Issues

README needs update for new CLI flag

README needs update for new CLI flag

Recommendation

Address documentation before merge.

undefined

Address documentation before merge.

undefined

pre-merge-checklist

Original

Translation

Pre-Merge Checklist

合并前检查清单

When to Use

使用场景

Instructions

操作说明

Automated Checks (Ordered)

自动化检查（按顺序）

1. Linting and Formatting

1. 代码规范与格式检查

Check linting

Check linting

Check formatting

Check formatting

Auto-fix (if needed before commit)

Auto-fix (if needed before commit)

Check linting

Check linting

Check formatting

Check formatting

Auto-fix (if needed)

Auto-fix (if needed)

2. Type Checking

2. 类型检查

3. Tests

3. 测试

4. Coverage

4. 测试覆盖率

5. Security Scan

5. 安全扫描

Python dependencies

Python dependencies

npm dependencies

npm dependencies

Custom code scan (if code-review-security skill is available)

Custom code scan (if code-review-security skill is available)

Manual Review Checklist

手动审查清单

Code Quality

代码质量

Testing

测试

Type Safety

类型安全

Error Handling

错误处理

Backwards Compatibility

向后兼容性

Documentation

文档

Performance

性能

Accessibility

无障碍性

Failure Protocol

失败处理流程

Override Process

例外审批流程

OVERRIDE: Coverage below 80% for this module. See TICKET-1234.

OVERRIDE: Coverage below 80% for this module. See TICKET-1234.

Approved by @tech-lead on 2024-01-15.

Approved by @tech-lead on 2024-01-15.

Reason: Legacy code migration in progress; full coverage planned for Sprint 12.

Reason: Legacy code migration in progress; full coverage planned for Sprint 12.

Examples

示例

Running All Checks

运行所有检查

Run the full check suite

Run the full check suite

Run only type checks

Run only type checks

Run accessibility checks

Run accessibility checks

Quick PR Review Workflow

快速PR审查流程

Output File