How should manual code edits be reconciled with OpenSpec?

[futbotism]

I understand that the OpenSpec flow is designed to keep openspec/specs/** as the source of truth, with changes proposed under openspec/changes/** and archived back into specs after implementation.

What I’m finding hard to reconcile is this:

If I directly edit code in my repo (instead of generating it from a spec/task), the specs don’t automatically know about those changes.

That seems to introduce “spec drift” — code and spec are no longer aligned. Like with the spec driven development can i edit my code manually as part of a bets practice workflow? or is all code to be written by my AI based on specs?

[TabishB]

This is a good question! In an ideal world any drift between code and spec should be "reconciled". Ideally this happens automatically without you having to worry about.

In these cases where a drift does occur, my view is it's ok to update the source of truth directly to match the changed implementation.

I'm looking at ways to see if this is possible to detect in a simpler automatic way, but up till then this process has to be manual unfortunately.

Similar to my comment on this other thread, I think the only 2 options are either

1. All changes happens through editing the spec first (which can be cumbersome especially for smaller edits)
2. Edit the code as much as you want and then there's something that can run towards the end to ensure any specs/proposals are updated correctly

[futbotism]

thanks for explaining this to me, its where i struggled with spec-kit.

tbh the idea of exclusively editing my code through agents feels off to me, in that regard i would feel better with something like option 2 where i can somehow catch the spec up with my updates and feed my back in.

[stargazer33]

2. Edit the code as much as you want and then there's something that can run towards the end to ensure any specs/proposals are updated correctly

You are describing the "memory bank" functionality in Kilo Code:

https://kilocode.ai/docs/advanced-usage/memory-bank#key-commands

update memory bank

[jadeftx]

If we are being really strict about it, then I think editing props/specs/tasks isn't the right way to handle such drift. If we could supersede the older or now incorrect/incomplete change with a new one, then all information/truth is preserved, and drifted changes can be properly captured into the process. We could have superseded prop chains move into a superseded folder or some such.

The downside to this of course is you accumulate superseded/incorrect/incomplete prop chains, but I don't know if that's actually a problem or not, as if it happens constantly, something else is breaking down that needs to be addressed.

[benoitheinrich]

I suppose it depends on the reason why did you have to make manual changes ?
a. is it because it wasn't specified correctly and a drift now exists that should be resolved / reconciled ? or
b. is it that you weren't happy with the actual code and you wanted to add your own touch and it still matches the original requirements ?

In case of a. you could reconcile by asking the LLM to retrofit analyse your changes and update the proposal/design/specs based on the delta.
In case of b. then nothing really needs to change since the specs didn't change.

In case of a large portion of the code being manually implemented outside of an openspec change, then maybe you can ask the LLM the generate an openspec proposal and specs based on the changes you've done, then you could validate the spec, ask LLM to review if it all matches your code changes, and if not you could either do some manual reconciliation or ask the LLM to do the reconciliation for you.

At the end you'll still need to verify what the LLM is doing and if it please you.

Finally you can archive that change like any other change.

Do you think this could work ?