Clarify custom checklist ownership and lifecycle - #4028
Conversation
There was a problem hiding this comment.
Pull request overview
Clarifies ownership and lifecycle semantics for custom versus built-in checklists.
Changes:
- Defines custom checklists as reviewer-owned requirements-quality artifacts.
- Makes implementation treat checklist markers as read-only gates.
- Documents distinct built-in
requirements.mdbehavior.
Show a summary per file
| File | Description |
|---|---|
docs/quickstart.md |
Updates checklist and implementation guidance. |
docs/reference/agentic-sdd.md |
Documents ownership and lifecycle distinctions. |
templates/commands/checklist.md |
Adds reviewer ownership rules. |
templates/checklist-template.md |
Defines checkbox semantics and lifecycle notes. |
templates/commands/implement.md |
Makes checklist state read-only during implementation. |
Review details
Tip
Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- Files reviewed: 5/5 changed files
- Comments generated: 1
- Review effort level: Balanced
| ### Step 8: `/speckit.implement` — build it | ||
|
|
||
| Executes the tasks in `tasks.md` in dependency order. Run it once to build everything, or scope it to one phase at a time for large features. | ||
| Executes the tasks in `tasks.md` in dependency order. Before implementation, it reads checklist checkbox state as a gate and asks before proceeding if any checklist items are unchecked; it does not change custom checklist markers. Run it once to build everything, or scope it to one phase at a time for large features. |
There was a problem hiding this comment.
Updated the quickstart implement step to state that implementation does not change any checklist files or markers, and called out that checklists/requirements.md is maintained by /speckit.specify and /speckit.clarify while custom checklists remain reviewer-owned.
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Please address Copilot feedback
|
Addressed the Copilot feedback by clarifying in the quickstart that implementation does not modify checklist files or markers, and by calling out that checklists/requirements.md is maintained by /speckit.specify and /speckit.clarify while custom checklists remain reviewer-owned. |
There was a problem hiding this comment.
Review details
Suppressed comments (3)
templates/checklist-template.md:39
- Use “requirements-quality” consistently with the ownership text above; “requirement-quality” here appears to be a typo.
- Mark items `[x]` only after review confirms the requirement-quality criterion is satisfied
templates/commands/checklist.md:148
- Reserve
requirements.mdwhen choosing the custom checklist filename. The current domain-derived naming can selectrequirements.md, and the append behavior would then mix reviewer-owned items into the built-in checklist that specify/clarify automatically update (or allow specify to overwrite a custom file).
- Leave every newly generated item unchecked (`[ ]`); checkbox state belongs to the reviewer
docs/quickstart.md:86
- Use “requirements-quality” consistently; this sentence currently switches to the singular form immediately after introducing “requirements-quality review artifacts.”
Generates a custom quality checklist — "unit tests for your requirements" — to confirm the spec is complete, clear, and consistent before you break the work down. These custom checklists are reviewer-owned requirements-quality review artifacts: mark an item `[x]` only when the reviewer determines that requirement-quality criterion is satisfied. Checked custom items do not mean implementation work is complete.
- Files reviewed: 5/5 changed files
- Comments generated: 0 new
- Review effort level: Balanced
Summary
/speckit.checklistoutputs are reviewer-owned requirements-quality artifacts.[x]markers as requirements-quality approval, not implementation completion./speckit.implementguidance to treat checklist markers as a read-only gate and distinguish the built-inchecklists/requirements.mdlifecycle.Closes #3979
Validation
git diff --check -- docs/quickstart.md docs/reference/agentic-sdd.md templates/commands/checklist.md templates/checklist-template.md templates/commands/implement.mdPYTHONDONTWRITEBYTECODE=1 .venv/bin/python -m pytest -p no:cacheprovider tests/test_command_template_py_scripts.py -q