On /speckit.checklist workflow

[armoucar-neon]

This is a new nice feature on speckit, but it is still a bit unclear when I should execute the step and how the agents/speckit helps me to verify all the items in the checklist. The checklist is generated with all blank checkboxes, but some of those bullets are covered in the specs some others are not ([Gap]).

The speckit docs tell me this should be executed after the /speckit.plan phase:

/speckit.checklist (optional) - Generate quality checklists to validate requirements completeness, clarity, and consistency (after /speckit.plan)

But if the checklist is pointing stuff that is unclear in my specs, won't I have to execute /speckit.plan again after adressing those in my spec/plan? And I guess if I execute /speckit.plan again, I will override all the current existing plan which I already 'human validated' before running /speckit.checklist.

What is the process for getting the checkboxes in the checklist complete? Should I go back to my spec.md/plan.md and manually update those files, then I go back to check the item?

[armoucar-neon]

Claude draw this, maybe it is easier to understand visually

  The Circular Dependency Problem

  ┌─────────────────────────────────────────────────┐
  │ /speckit.specify → spec.md + requirements.md    │
  │          ↓                                      │
  │ ✅ Check off requirements.md (spec validated)   │
  │          ↓                                      │
  │ /speckit.plan → plan.md, data-model.md, etc.    │
  │          ↓                                      │
  │ /speckit.checklist api → api.md                 │
  │          ↓                                      │
  │ ❌ Find spec gaps (e.g., "Are rate limits       │
  │    defined for all endpoints?")                 │
  │          ↓                                      │
  │ 🤔 Fix spec.md → plan.md is now STALE           │
  │          ↓                                      │
  │ /speckit.plan → ⚠️  OVERWRITES previous plan    │
  │          ↓                                      │
  │ Lost all human review work on plan.md!          │
  └─────────────────────────────────────────────────┘

  | Scenario                            | Problem                                                             |
  |-------------------------------------|---------------------------------------------------------------------|
  | Domain checklist finds spec.md gaps | Must fix spec → must regenerate plan → lose plan review work        |
  | Domain checklist finds plan.md gaps | Edit plan.md directly → breaks "spec as source of truth" philosophy |
  | Domain checklist finds minor issues | Maybe acceptable to edit directly? → No clear guidance in docs      |

[armoucar-neon]

I was able to update my spec and then just update the plan too without overriding by doing:

/speckit.plan We already have a plan in place: @specs/001-[spec-name]/plan.md

We recently did some updates to @specs/001-[spec-name]/spec.md (use git to check the diffs, the file isnt commited yet). Those updates should be reflected in the plan.

DO NOT RECREATE THE PLAN FROM SCRATCH, READ ALL THE CURRENT PLAN FILES AND UPDATE ACCORDINGLY.

[bizcad]

Good Idea

I customized a lot of the original spec-kit files and would not want to lose the changes. - I am currently finished with the plan.md and want a checklist to look for inconsistencies. - I am about to run spec-kit.implement

I think the answer is to look in the spec-kit repo for files that have changed since I did my init command