You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
From the docs, OpenSpec keeps a source-of-truth per domain at openspec/specs/domain/spec.md,
During archive, those deltas are merged into the main spec.
I’m looking for official strategies/best practices to ensure multiple changes that affect the same area converge into a single domain spec.
this is a real case that happen to me:
First change — user-show
I created a feature to display users and ran it through the full flow:
/opsx:new "user-show" → /opsx:ff → /opsx:apply → /opsx:archive
Second change — user-detail
The next day I created a feature that adds extra details on the same page introduced by user-show:
/opsx:new "user-detail" → /opsx:ff → /opsx:apply → /opsx:archive
What I see now
OpenSpec correctly recognized some overlap and integrated parts of the second change into the source-of-truth spec created by the first change.
However, I currently have two specs in the repository:
openspec/specs/user-show/spec.md
openspec/specs/user-detail/spec.md
My intention was to end up with a single spec (I would have named it user-mangament) because, functionally, these two features are tightly connected. I split the work only for practical reasons: deliver the first piece, test/integrate, then proceed with the next piece, when the tester in parallel was verifying the first one
Imagine doing it as a CRUD and delivering it in stages. I would end up with four specifications instead of one, especially if we have to implement and deliver each functionality one by one for any valid reason
Questions
1 - How can I force both changes to land in the same domain spec?
Is there a recommended way to ensure that subsequent changes affecting the same functional area always converge into one existing domain (so that I don’t end up with multiple domain folders for closely related features)?
2 - Should I have used a broader domain name from the start?
For example, should I have created a domain like "user-management" (and reused it) both times:
/opsx:new "user-mangament" ..... /opsx:archive (phase 1)
/opsx:new "user-mangament" ..... /opsx:archive (phase 2)
so that both user-show and user-detail changes archive into the same openspec/specs/user-management/spec.md?
NOTE: this one i tested and in same way it works, but i see two interesting points:
when you archive the second change, if the days are the same there is a conflict because openSpec try to recreate the same folder in the archive repository with the same name (dd-mm-yyy is part of the name) --> OpenSpec propose you to rename or delete the old one
during the second change OpenSpec update directly the spec of the source of true during the creation (/opsx:new) then continuing whit the flow it anyway recreated correctly also the spec in the change folder and there was any issue during the final merge
3 - Best practices
Are there recommended strategies or best practices to:
choose and reuse the right across multiple related changes, and
avoid fragmenting the source-of-truth into multiple specs when features are tightly coupled but delivered in stages?
Thanks in advance to share your experience and strategies.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
From the docs, OpenSpec keeps a source-of-truth per domain at openspec/specs/domain/spec.md,
During archive, those deltas are merged into the main spec.
I’m looking for official strategies/best practices to ensure multiple changes that affect the same area converge into a single domain spec.
this is a real case that happen to me:
First change — user-show
I created a feature to display users and ran it through the full flow:
/opsx:new "user-show" → /opsx:ff → /opsx:apply → /opsx:archive
Second change — user-detail
The next day I created a feature that adds extra details on the same page introduced by user-show:
/opsx:new "user-detail" → /opsx:ff → /opsx:apply → /opsx:archive
What I see now
OpenSpec correctly recognized some overlap and integrated parts of the second change into the source-of-truth spec created by the first change.
However, I currently have two specs in the repository:
openspec/specs/user-show/spec.md
openspec/specs/user-detail/spec.md
My intention was to end up with a single spec (I would have named it user-mangament) because, functionally, these two features are tightly connected. I split the work only for practical reasons: deliver the first piece, test/integrate, then proceed with the next piece, when the tester in parallel was verifying the first one
Imagine doing it as a CRUD and delivering it in stages. I would end up with four specifications instead of one, especially if we have to implement and deliver each functionality one by one for any valid reason
Questions
1 - How can I force both changes to land in the same domain spec?
Is there a recommended way to ensure that subsequent changes affecting the same functional area always converge into one existing domain (so that I don’t end up with multiple domain folders for closely related features)?
2 - Should I have used a broader domain name from the start?
For example, should I have created a domain like "user-management" (and reused it) both times:
/opsx:new "user-mangament" ..... /opsx:archive (phase 1)
/opsx:new "user-mangament" ..... /opsx:archive (phase 2)
so that both user-show and user-detail changes archive into the same openspec/specs/user-management/spec.md?
NOTE: this one i tested and in same way it works, but i see two interesting points:
3 - Best practices
Are there recommended strategies or best practices to:
choose and reuse the right across multiple related changes, and
avoid fragmenting the source-of-truth into multiple specs when features are tightly coupled but delivered in stages?
Thanks in advance to share your experience and strategies.
Beta Was this translation helpful? Give feedback.
All reactions