Handling Modifications in the Spec Kit Workflow

[XKonstX]

Modifications to implemented features are an inevitable part of the development lifecycle, necessary for improvements or corrections.

The key question is: What's the right approach for applying modifications to features developed using the spec kit workflow?

My current thinking: If a complete feature has been implemented and is considered "done," but an improvement or fix is later required, treating the modification as a brand-new feature seems wrong. The original feature needs modification.

I believe an impact analysis based on the proposed modifications is the best path forward, but I'm unsure if a structured approach for this exists within the current spec kit tooling or methodology.

[wilsonneto-swe]

The usual way I am solving it is asking the agent to check my last updates and fix/apply any needed update in the spec and adding a follow-ups section in the plan with the changes. If I am planning to change I also ask the agent the same but also to add the new tasks.

So that way the spec will still be updated, for docs purpose the plan will show how the things really went, the plan execution + some follow up fixes.

But yes, a more structured way or a command to do that would be great.

[thlandgraf]

This is exactly the problem that pushed me toward building a separate entity type for modifications. The approach I settled on:

Once a spec hits approved status, it's locked — no direct edits. If something needs to change, you create a Change Request: a separate Markdown file that references the original spec by ID, describes what's changing and why, and goes through its own draft → review → approved cycle. When the CR gets approved, it merges into the original spec (updated in place), and the CR itself gets archived.

The mental model is that the spec file always reflects current behavior. The CR archive is how that behavior evolved. Git history captures the diffs, but the CR entities capture the intent behind each change — which is what you actually need when someone asks "why does this work this way?"

speclan/features/F-1234-auth/
├── F-1234-auth.md                    ← current spec (locked after approval)
└── change-requests/
    └── CR-5678-add-oauth.md          ← proposed modification (own review cycle)

The key insight for me was that most spec drift happens because editing specs is frictionless — nothing stops someone from silently changing a spec. Adding friction (status locking + formal CRs) sounds annoying but it's what makes the spec actually trustworthy as a source of truth.

Full disclosure: I'm the creator of SPECLAN, a VS Code extension built around this model. The status lifecycle and Change Request entity are core features. Happy to discuss tradeoffs — the CR workflow adds overhead that solo devs might not want.

[mnriem]

Note that Spec Kit now supports extensions and presets if you want to augment your workflow with new commands, or create an entirely new workflow. Or presets if you want to override existing commands (both in core and extensions). See main README.md for more information.