Evolving specs

[Ian1971]

Using the spec kit I create a spec and implement it.
What is the process when I now have a change request. Spec driven development would seem to indicate that the spec is the source of truth for the system, but spec kit leads me to create a new spec with the variation. That doesn't seem to be in keeping with spec driven development, as now to know what the system does I need to read both specs.

Or should I be getting the AI to update the master spec as well?

[simongartz]

You should not change the master spec, if you create a feature you just add the spec with the new feature. If you change you say that you change that in the new spec.

Ex.

spec1 - Todo list with local storage
spec2 - Add login
spec3 - Replace file storage with option to use cloud storage - This one replaces the implementation of the local storage with a cloud storage, to comply with the change request.

[Ian1971]

ok, thanks for that. So the source of truth is the chain of specs right?

[simongartz]

yes that's correct!

[colinmacleod]

@simongartz I'm confused by this. If I specify a feature, and then later decide to change the feature, do I change the spec.md of the already-created feature? How do I plan, then implement this?
If changes are "new features", won't your evolving spec get messy?

[colinmacleod]

Like agile user stories, in Spec Kit, it appears each spec.md is not a project-scope document as I had originally assumed. It's implementation-scoped, effectively to be discarded after the tasks have been completed.
You can follow the trail (in the same way as you can for user stories) - but it seems there is no "single source of the truth."

[erf1nd0r]

Thank you @simongartz for your explanation. Where I personally have a hard time understanding is, that for each spec one git branch is created. Based on your example: spec1 is the todo list with local storage. So the tasks on a high-level would be like create project structure, create tests, implement the todo list with local storage.
This sounds like a lot of stuff being done in just one branch. Getting a PR like this to review sounds not manageable to me.
Am I missing something? I didn't find a proper explanation in the documentation.

[rafaelassumpcao]

Pardon my ignorance, but what would be your expectations if not a PR containing code + tests (considering project structure as a tight dependency ofc)

[erf1nd0r]

Hehehe. Thank you for your reply. This is exactly what I am expecting. I think, I have a hard time explaining what I don't understand.

Let's go with the example from the documentation.
/specify Real-time chat system with message history and user presence

This creates the branch 003-chat-system.

My point is, shouldn't the implementation of this specification be split into smaller features (and branches)? Especially when the specification is split into tasks (after the planning), shouldn't these tasks be the features that should be put in feature branches?

I know, that I can do this manually and generate my own branches for each task.
What I want to understand is, what is the proposed workflow with SDD? For me right now, it looks like each specification is generating one branch. But this doesn't sound right, especially if I want to build something from scratch and not only specify one feature.

[simongartz]

The first spec can be quite large if you are building a large system from the get go. You could also decide to no put everything into the first spec, create an overarching roadmap for the system you want to build and create a spec for different parts of the system you defined in the roadmap.

Regarding the branching in git. I don't think you should bother too much about the branching, it's not a necessary building block for spec driven development.

[Ian1971]

The way I am thinking about it, for an existing mono repo project, is to have a spec project per broad feature, then each feature will have a trail of specs that will define its truth. I'm not sure yet if speckit in its current form works with that because I'd essentially want many spec projects at the src root (one for each broad feature). Not sure if this is "correct" or not, but currently the only way I can think to get it to work for a large existing brownfield project.