Improving the spec update workflow (1→n)

[favoyang]

As OpenSpec documentation says, it’s not only designed for 0→1 (initial design) but also excels at 1→n — evolving existing behaviors. I’ve been experimenting with this flow using Codex (GPT-5-Codex model) and wanted to share my experience.

What I did

1. Initial proposal

   • Created a proposal, applied it, and archived it.
   • This generated a new spec folder, e.g. auth-system, representing the current truth.

2. Follow-up modification

   • Wrote a new proposal for the same component (auth-system) but didn’t explicitly mention the current spec folder.
   • After applying and archiving, the system did detect and try to modify the existing spec.
   • However, it didn’t preserve unrelated sections of the spec very well — some existing specs were swept away instead of being merged intelligently.
   • I had to manually follow up with prompts to tell it to “only modify related specs and keep existing ones intact.”

Thoughts

This makes me wonder if the update/merge logic can be improved when dealing with partial or incremental proposals. Maybe OpenSpec could:

• Automatically diff and merge new proposals with the previous spec more safely.
• Detect and preserve unrelated sections of the existing spec.
• Warn when a proposal might overwrite broader parts of the spec than intended.

Questions for the community

• How do others handle incremental updates to the same spec?
• Do you usually reference the previous spec explicitly in the proposal text?
• Would some change to the /prompts:openspec-archive command make a safer merge possible?