Skip to main content

Master Checklist Template

Source: .agents/references/implementation/master-checklist-template.md

Content​

Master Checklist Template

The master checklist must exist in both:

  • The live chat/task tracker.
  • A temporary plan file under plan-docs/<feature>-master-checklist.md.

The temporary file exists for resumability only. It is deleted after all tasks pass and integration completes unless the user asks to keep it.

Allowed Statuses​

  • planned
  • blocked
  • in-progress
  • implementation-done
  • qa-failed
  • review-failed
  • passed
  • merged

Checklist Format​

Use this exact shape for every task:

## Master Checklist

- [ ] Task ID:
  - Title:
  - Owner:
  - Worktree:
  - Branch:
  - Env files: copied | skipped-no-source-env | not-needed
  - Status: planned | blocked | in-progress | implementation-done | qa-failed | review-failed | passed | merged
  - Requirement:
  - Acceptance criteria:
  - Affected page/route:
  - Playwright coverage: required | blocked | not-applicable
  - Playwright spec:
  - Playwright cases:
  - Playwright command:
  - Playwright result:
  - Playwright blocker or not-applicable reason:
  - Files likely affected:
  - Write scope:
  - Dependencies:
  - Conflict responsibility:
  - Context references:
  - Codebase-memory project/root:
  - Graph searches/traces:
  - Graph or shell fallback notes:
  - Tests/checks:
  - QA result:
  - Code review result:
  - Retry count:
  - Notes:

Task Breakdown Rules​

  • Each task must be small enough for one owner to complete independently.
  • Each task must have a clear write scope.
  • Tasks likely to edit the same files must be merged or explicitly ordered.
  • Prefer dependency order over maximum parallelism when file ownership is uncertain.
  • Every task with a newly created worktree must record whether .env and .env.* files were copied from the source checkout or skipped because none existed.
  • Keep task IDs stable across retries.
  • Increment Retry count after every failed QA or code review loop.

Dependency Section​

The checklist file must also include:

## Dependencies

- Task ordering:
- Shared files:
- Lark channel link: provided | skipped | not-applicable
- External/API dependencies:
- API integration mode: provided | ui-only | blocked | not-applicable
- UI-only exclusions:
- Conflict ownership:
- Feature references loaded:
- Coding standards loaded:
- Codebase-memory project/root and index status:
- Architecture/search/trace evidence:
- Graph refresh required after integration: yes | no
- Shell-search fallbacks and reasons:
- Risks:

Page Test Inventory​

Add one entry for every affected page or route:

## Page Test Inventory

- Page/route:
  - Owner task/subagent:
  - Playwright coverage: required | blocked | not-applicable
  - Spec: playwright/tests/<page-slug>.spec.ts
  - Top-level describe: <route-or-page>
  - Planned cases:
  - Command: bun run playwright:test -- playwright/tests/<page-slug>.spec.ts
  - Result: not-run | passed | failed | blocked
  - Blocker or not-applicable reason:

Map shared-component changes to every page that exercises the changed behavior. Assign each required spec to that page's implementation owner. Use not-applicable only when the feature has no user-facing page impact, with a recorded reason.

Completion Rules​

  • Mark a task implementation-done only after the worker reports changed files and tests/checks.
  • Do not mark a page task implementation-done until its required Playwright spec exists and the recorded page-level command passes. Keep a task blocked when a required spec cannot run because a prerequisite is missing.
  • Mark a task passed only after QA and code review both pass.
  • Mark a task merged only after the passed work is integrated into the final branch/worktree.
  • Never delete failed feedback from the checklist; append updated results.
  • A task with unresolved or incorrectly resolved conflicts cannot be marked passed.