fleet/docs/Contributing/reference/issue-specification-checklist.md

Engineering Spec Review Checklist

This document is a checklist for reviewing design docs and translating them into well-specified engineering subtasks in the Fleet repository.

The goal is to ensure issues are actionable, testable, and complete before implementation begins, reducing ambiguity and rework.

---

Global Checklist (Applies to All Sub-Issues)

Before reviewing individual areas, confirm:

• Problem & goal are clearly stated
  • What user or system behavior is changing?
  • What does “done” look like?
• Out of scope is explicitly defined
• Assumptions are listed
• Backward compatibility is considered
• Failure modes & edge cases are acknowledged
• Rollout and migration plan exists (if applicable)
• Acceptance criteria are concrete and testable
• Documentation impact is noted (Fleet docs, API docs, changelog)
• Security & permissions implications are reviewed
• Observability impact is noted (logs, metrics, errors)

---

Frontend Sub-Issue Checklist

UX & Behavior

• Entry points in the UI are defined
• User roles & permissions are specified
• Happy path UX is described
• Error, loading, and empty states are defined
• Copy/text is provided or guidance is given
• Feature flag usage is specified (if applicable)

Data & API Interaction

• Required API endpoints are listed
• Request and response shapes are documented
• Pagination, sorting, and filtering behavior is specified
• Caching or refetching strategy is noted
• Real-time updates or polling expectations are defined

Design System & Consistency

• Existing components are identified or new ones are justified
• Consistency with Fleet UI patterns is verified
• Accessibility considerations are noted (ARIA, keyboard, contrast)

Testing

• Unit test expectations are defined
• Integration / UI test expectations are defined
• Manual QA steps are outlined

---

Backend Sub-Issue Checklist (Including REST APIs)

API Design

• New vs existing endpoints are clearly identified
• HTTP methods and routes are specified
• Request schema is fully defined
• Response schema is fully defined
• Error responses and status codes are listed
• API versioning strategy is noted (if modifying existing APIs)
• Idempotency considerations are addressed (where applicable)

Authorization & Security

• Required permissions and roles are explicitly stated
• Authentication context usage is defined
• Input validation rules are documented
• Potential abuse or misuse scenarios are considered

Data Model & Storage

• Database schema changes are specified (tables, columns, indexes)
• Migrations are described (forward and rollback)
• Data lifecycle considerations are defined
• Performance impact is considered (queries, indexing)

Business Logic

• State transitions are clearly described
• Edge cases and invalid states are defined
• Side effects are documented (events, async jobs, webhooks)
• Consistency guarantees are explained

Testing & Docs

• Unit test expectations are defined
• Integration test expectations are defined
• API documentation updates are noted
• Backward compatibility tests are considered

---

Agent Sub-Issue Checklist

Behavior & Compatibility

• Agent behavior changes are clearly described
• OS/platform scope is specified (macOS, Windows, Linux, etc.)
• Minimum supported versions are noted
• Compatibility with older Fleet servers is considered

Config & Communication

• New configuration options are documented
• Default behavior is specified
• Server ↔ agent contract changes are explicitly listed
• Failure and retry behavior is defined

Performance & Reliability

• Performance impact is considered (CPU, memory, disk, network)
• Error handling and logging behavior is defined
• Offline or degraded-mode behavior is specified

Rollout & Safety

• Feature flags or gradual rollout strategy is defined
• Upgrade and migration behavior is described
• Recovery strategy for failures is noted

Testing

• Unit test expectations are defined
• Integration or end-to-end test expectations are defined
• Manual testing steps are included

---

GitOps Sub-Issue Checklist

Configuration & Schema

• YAML schema changes are fully specified
• Before/after examples are provided
• Validation rules are defined
• Default values are clarified

Sync & Drift Behavior

• How changes are detected and applied is described
• Conflict resolution rules are specified
• Drift detection behavior is explained

Errors & Safety

• Failure behavior is defined (partial apply, rollback, stop)
• Error messages are clear and actionable
• Safeguards against destructive changes are considered

Compatibility & Migration

• Backward compatibility is addressed
• Migration path is documented
• Interaction with existing Fleet GitOps flows is reviewed

Testing & Docs

• Unit or integration test expectations are defined
• Example repositories or fixtures are referenced
• Documentation updates are called out

---

Reviewer Red Flags

Reviewers should push back if a spec includes:

• ❌ “Implementation details TBD”
• ❌ Missing API request/response shapes
• ❌ “Handle errors” without specifics
• ❌ No migration plan for data or configuration changes
• ❌ Implicit behavior changes not explicitly acknowledged
• ❌ No clear acceptance criteria

---

Usage

This checklist should be used when:

• Reviewing design docs
• Creating or refining engineering subtasks
• Assessing readiness for implementation

Specs do not need to be verbose, but they must be complete.