Re-validate spec quality checklist after clarify updates spec#2715
Merged
mnriem merged 5 commits intoMay 27, 2026
Conversation
After clarify modifies spec.md, the existing checklists/requirements.md (generated by specify) can become stale. Items like 'No [NEEDS CLARIFICATION] markers remain' may now pass, and newly added requirements aren't reflected in the checklist evaluation. Add step 8 to the clarify command that re-validates the spec quality checklist against the updated spec after each clarification session: - Check/uncheck items based on current spec state - Report before/after pass counts in the completion report - Skip silently if no checklist exists Fixes github#2693
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the /speckit.clarify command template so that, after spec.md is modified, an existing spec quality checklist (checklists/requirements.md) is re-validated and the completion report reflects the updated checklist status (addressing stale checklist results after clarification).
Changes:
- Adds a new execution step to re-validate
FEATURE_DIR/checklists/requirements.md(when present) and capture before/after pass counts. - Expands the Completion Report requirements to include checklist status and changed/remaining items.
- Updates “Done When” criteria to include checklist re-validation and checklist status reporting.
Show a summary per file
| File | Description |
|---|---|
templates/commands/clarify.md |
Adds checklist re-validation instructions, completion reporting details, and updated done criteria to keep the spec quality checklist aligned with clarified spec changes. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 2
- Constrain re-validation to GitHub task-list checkbox lines only (- [ ] / - [x] outside code fences), ignoring headings, notes, and non-checkbox content - Define pass counts as checked/total checkbox items - Use FEATURE_DIR/checklists/requirements.md in Done When for consistency with the rest of the template
- Clarify that each checkbox is set based solely on current spec state, regardless of prior marker (checked->unchecked is possible) - Completion report now lists both newly passing items and regressions (checked->unchecked) so users see what became non-compliant
- Accept [x], [X], and leading whitespace for nested task items - Explicitly state only the [ ]/[x] marker is toggled; all other file content (headings, metadata, notes, ordering, whitespace) must remain unchanged to avoid noisy diffs
- Add explicit before-snapshot step to capture each item's prior marker state before re-evaluation - Compute three lists for the report: newly passing, regressions, and still unchecked - Only toggle markers whose checked/unchecked state actually changes; preserve existing case ([x]/[X]) when state is unchanged to avoid cosmetic diffs
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
After
/speckit.clarifymodifiesspec.md, the existingchecklists/requirements.md(generated by/speckit.specify) can become stale. Items like "No [NEEDS CLARIFICATION] markers remain" may now pass, and newly added requirements aren't reflected in the checklist evaluation.This adds a re-validation step to the clarify command so the spec quality checklist stays in sync with spec changes.
Changes
Three modifications to
templates/commands/clarify.md:checklists/requirements.mdif it exists, updating check marks and recording before/after pass countsBehavior
FEATURE_DIR/checklists/requirements.mddoes not exist, the step is skipped silently (no breaking change)- [x]), items that still fail remain unchecked (- [ ])Testing
This is a template-only change (AI agent prompt instructions). It requires no code changes or unit tests. Validation is through running
/speckit.clarifyin a project that has an existingchecklists/requirements.mdand confirming the checklist is updated.Fixes #2693
cc @yag3l