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 ?

[thlandgraf]

This is exactly what pushed me toward building a status lifecycle into my spec tooling. The approach:

• Each spec file has a status field in the YAML frontmatter: draft → review → approved → locked
• Once a spec is "approved," the file becomes read-only — you can't silently edit it
• If code changes invalidate a spec, you create a Change Request — a separate file that proposes the modification, references the original spec, and tracks approval

The Change Request is the reconciliation mechanism. It answers "why did this spec change?" with a traceable artifact rather than a silent edit.

In practice, most spec drift happens because editing specs is frictionless — there's nothing stopping someone from changing a spec without anyone noticing. Adding friction (status locking + formal change requests) sounds annoying but it's what makes the spec actually useful 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 to how it handles spec drift. Happy to discuss tradeoffs.

[idanshimon]

my 2 cents

The manual approach works but relies on the developer remembering to reconcile which is the weak link. what I think is missing is detection. In practice, quick fixes happen in plan mode or even direct edits at 11pm, and nobody remembers to sync the specs after. By the time you open the next session, the specs are stale and the agent is working from outdated context.

A few ideas on how this could be solved more systematically:

1. Post commit spec drift detection. A git hook or skill that runs after commits and diffs changed files against the current specs. If files covered by a spec changed outside of an active OpenSpec change, it flags: "these files changed but no spec reflects it, reconcile?"

2. Session start reconciliation check. so when you run any /opsx: command, have it compare the codebase state against the last archived specs. If there's drift, surface it before you start new work. Otherwise you're proposing changes on top of a stale foundation.

Would love to see something like a /opsx:reconcile command that handles this flow natively.

[JannikStreek]

I would prefer the first option, as reconciliation checks when adding the next feature would create unrelated content for the next task. However, I am also not a big fan of git hooks.

Ideally, it would be possible to integrate this in a CI pipeline. That would be really great, to automatically check your specs on the CI for drift. So far I came up with my own reconciliation commands for Claude Code which at least work locally and can be run after smaller bug fixes. Works for now.

[geedeezet]

Very interested in especially the first option, some kind of hook or skill that checks on each commit if the specs are still covering the changes. If not, offer to adjust / extend the specs in the current change (add-on specs?)

For a development team which works with Azure DevOps (with lots of brownfield code) this would be great for the adoption of SDD with OpenSpec (or any other SDD framework).
I believe that small, manual changes should not lead to a complete redesign of the specs, and breaking sprints, new refinements etc...

[aa333]

I strongly believe in "code itself is a detailed spec, and PRD level specs are for additional context", so bidirectional flows would really help me use OpenSpec. However, I'll understand if you are going to focus on one-way flow.

[thlandgraf]

@aa333, the code-as-spec position is honest about something most spec advocates dodge: implementation IS the most detailed and most current description of behavior. Any spec that says otherwise is just a model of the code, and models drift.

Where it breaks down for me is the question "why does the system do this specifically?" calculateDiscount(qty, tier) tells you exactly what happens when qty is 500 and tier is gold. It does not tell you that the 12% tier-3 break was the result of a 2024 contract negotiation with one specific account that the PO is contractually bound to honor. That's not "additional context" you can reverse-engineer from the code; it's load-bearing intent that lives only in the heads of the people who originally negotiated it, and the next person who edits the tier table will silently break the contract.

Bidirectional flow is the right ask, but I'd push on the framing: the two directions are not symmetric. Code -> spec is mechanical (the LLM can diff the change and reconcile structurally). Spec -> code is intentional (someone has to decide the change is wanted before code follows). Conflating them is what makes "auto-sync" usually mean "auto-overwrite the spec whenever code changes", which is exactly the silent-drift failure mode the thread is asking about.

@idanshimon's post-commit detection idea is the bridge I'd bet on: surface the drift as a question (was this a fix, an intentional change, or an unintentional one?), don't auto-reconcile. The agent doesn't know which of @benoitheinrich's (a) vs (b) cases it is. The human does.

[adamlusted-wiq]

Normally, if there is a small change that I know i can resolve quickly, I'll commit that change and quickly

/opsx:propose something around the lines of,

"i've just added a manual change to the repository, can you please update any specs that need updating due to this change"

The agent will then look at the commit's and create a new change that can be synced.

---

I think a custom command would be useful like /opsx:reconcile which would check the change is all in line. I also will sometimes add extra tasks for small tweaks to the spec that will also need a "reconcile".