template/docs/CHECKLISTS.md

Checklists

Use these concise checklists as quality gates. Expand them only when repeated project experience proves that more detail is necessary.

For workflow details, see workflow.md. For code standards, see CONVENTIONS.md. For releases, see release-process.md.

Feature Development

• Objective and acceptance criteria are clear.
• Relevant docs and existing implementation were read.
• Architecture boundaries are respected.
• User-facing behavior is implemented.
• Edge cases and failure states are handled.
• Tests or manual checks cover the main behavior.
• Documentation is updated when behavior or setup changed.

Bug Fix

• Observed behavior is understood.
• Expected behavior is confirmed.
• Root cause is identified before changing code.
• Fix is scoped to the cause.
• Regression coverage is added when practical.
• Validation proves the bug is fixed.
• Remaining risk is documented.

Refactoring

• Behavior-preserving intent is explicit.
• Existing tests or checks are identified.
• Changes are small and reviewable.
• Public contracts remain stable or the break is approved.
• Dead code is removed only when safe.
• Validation is run before and after meaningful changes.

API Review

• Consumer needs are clear.
• Request and response contracts are stable.
• Validation errors are consistent.
• Authorization is explicit.
• Pagination, filtering, and sorting are defined where needed.
• Idempotency is addressed for retryable writes.
• Versioning and compatibility are considered.

Database Review

• Data ownership is clear.
• Constraints protect important invariants.
• Indexes match expected query patterns.
• Migration is reversible or rollback-safe.
• Backfill and deployment order are documented.
• Retention and privacy requirements are addressed.
• Backup and restore impact is understood.

Security Review

• Authentication is required where expected.
• Authorization is enforced server-side or at the trusted boundary.
• Inputs are validated.
• Outputs are safely encoded or serialized.
• Secrets are not logged or committed.
• Sensitive data exposure is minimized.
• Dependency risk is reviewed.
• Abuse cases and rate limits are considered where relevant.

Performance Review

• Hot paths are identified.
• Database queries are bounded and indexed.
• Network calls have timeouts and retry policy where appropriate.
• Expensive work is cached, batched, async, or justified.
• UI updates avoid unnecessary re-rendering where relevant.
• Performance expectations are measurable.

Pull Request

• Summary explains what and why.
• Scope is focused.
• Tests or checks are listed.
• Screenshots or recordings are included for UI changes.
• Migration and deployment notes are included when relevant.
• Risks and follow-ups are documented.
• No secrets, debug code, or unrelated files are included.

Release

• Release scope is defined.
• Required checks passed.
• Database migrations are reviewed.
• Configuration and secrets are ready.
• Rollback plan exists.
• Monitoring and alerting are ready.
• Stakeholders are informed.

Production Readiness

• Runtime environments are documented.
• Health checks exist.
• Logs include correlation identifiers.
• Backups and restore process are tested or scheduled.
• Alerts cover availability and critical failures.
• Security-critical settings are production-safe.
• Operational runbooks exist for common failures.