open:sync messed up my spec.md files

[yhwelcome1981-debug]

Hey folks,

I'm a bit confused about open:sync and hoping someone can shed some light.

I ran open:sync the other day, and now my spec.md files look different from what I expected. It's like they're not fully synced, or something got changed unexpectedly.

My main questions are:

Why did this happen? What usually causes spec.md to be different after open:sync? Is it something I'm doing wrong, or is there a common scenario for this?
How do I fix it? If my spec.md is now weird, what's the best way to get it back to normal without losing my work? Are there any commands to help me see the differences or merge them?
How can I avoid this in the future? Any tips or best practices for using open:sync with Git (like when to commit, when to run sync) so this doesn't happen again?

[1code-async]

Task completed.

I'll analyze this issue by exploring the codebase to understand how open:sync works and what could cause spec.md files to be modified unexpectedly.

---

View full conversation

Powered by 1Code

[1code-async]

Issue Triage: open:sync and spec.md behavior

Thanks for reporting this. Here's a breakdown of what's happening and how to address each of your questions.

---

Why did this happen?

/opsx:sync merges delta specs (from openspec/changes/<change-name>/specs/*/spec.md) into your main specs (at openspec/specs/*/spec.md). The key behavior that likely surprised you:

• MODIFIED operations replace entire requirement blocks — they don't do a fine-grained merge. If your delta spec has a ## MODIFIED Requirements section, the entire requirement body in the main spec gets replaced with the delta version (src/core/specs-apply.ts:272-286).
• Ordering may change — after sync, requirements are recomposed in a specific order (RENAMED first, then REMOVED, MODIFIED, ADDED), which can rearrange the output compared to what you had before.
• No conflict detection for parallel changes — if you had multiple changes touching the same spec, the second sync silently overwrites what the first one wrote. This is a known limitation with planned improvements.

Common scenarios that cause unexpected results:

Scenario	What happens
Delta has MODIFIED section	Entire requirement block is replaced, not merged
Multiple changes target the same spec	Later sync overwrites earlier one
Delta was written against an older version of the spec	New content from other changes can be lost

---

How to fix it

1. Check what changed — use git diff on your openspec/specs/ directory to see exactly what sync modified:

   git diff openspec/specs/
   

2. Revert if needed — if you committed before syncing, you can restore the previous version:

   git checkout HEAD -- openspec/specs/
   

3. Re-sync selectively — after reverting, you can run /opsx:sync <change-name> targeting a specific change, then review the diff before committing.

4. Validate specs — run /opsx:status to check if your specs are still structurally valid.

---

How to avoid this in the future

Per the command documentation:

• Commit before syncing — always commit (or stash) your current state so you can revert if the merge isn't what you expect.
• You often don't need to call sync directly — the archive command prompts for sync if needed. Most users never need to run /opsx:sync manually (docs/commands.md:388).
• Review the diff after sync — run git diff immediately after sync to verify the changes look correct before committing.
• One change at a time for the same spec — if two changes target the same spec, archive the first before syncing the second. Parallel changes to the same spec are a known source of silent overwrites.
• Use sync for preview — sync is useful when you want to preview what the merge looks like before archiving (docs/commands.md:432).

---

Related issues

• Feature Request: Target Main Specs on Sync and Archive #827 — Feature request to target specific main specs during sync/archive, which would help prevent unintended modifications to other specs.
• What's the point to maintain main specs? #878 — Discussion about the purpose of maintaining main specs, related to the broader sync workflow questions.

Relevant code and docs

Resource	Path
Sync merge logic	src/core/specs-apply.ts
Delta spec parsing	src/core/parsers/requirement-blocks.ts
/opsx:sync command docs	docs/commands.md#L386-L440
Delta specs concept	docs/concepts.md#L346-L405
Parallel merge plan (known limitations)	openspec-parallel-merge-plan.md
Sync workflow template	src/core/templates/workflows/sync-specs.ts

[TabishB]

How do I fix it? If my spec.md is now weird, what's the best way to get it back to normal without losing my work? Are there any commands to help me see the differences or merge them?

You don't need special commands! The beauty of LLM's is you can just ask the model to go and fix it, you can literally prompt it to say "hey can you check if this is now wrong, if so what would the fix be?"

Why did this happen? What usually causes spec.md to be different after open:sync? Is it something I'm doing wrong, or is there a common scenario for this?

I would need more details here. Can you maybe retrieve the agent session to give more info?

sync looks at your current change proposal and tries to sync it to the source of truth specs manually.

But hard to say without a proper agent trace.