Repository navigation
Best practices for ensuring spec integrity during archiving and PR review #2268
Replies: 1 comment
|
I'd put the archive on a short follow-up PR if The archive skill checks that the requested additions, edits, removals, and renames landed in each affected capability. The CLI validator checks the resulting spec structure. A semantic review can catch a different class of mistakes. For example, a modified requirement could keep its heading while accidentally dropping an exception that appeared in a previous scenario. Compare the final requirement and its scenarios with both the old spec and the approved delta. Archive verification spec Archiving inside the implementation PR makes sense if the final spec and code must land together. The extra review noise comes from seeing the implementation, canonical specs, and moved change artifacts in the same diff. Keeping the archive in a separate commit within that PR gives reviewers a way to inspect the two changes separately while still merging them together. |
Uh oh!
There was an error while loading. Please reload this page.
Thanks to the OpenSpec team for building a structured SDD workflow!
I'd like to discuss a potential spec review gap in the post-merge archive workflow.
Context
According to the [OpenSpec team workflow guide](https://github.com/Fission-AI/OpenSpec/blob/main/docs/team-workflow.md#the-everyday-loop), the recommended approach is to review and merge a PR (including delta specs and code), then run
/opsx:archiveto sync the delta specs into the main specs.Our team's concern is that the resulting main specs are updated after the PR has already been reviewed and merged. Reviewers validate the delta specs and code, but don't necessarily review the final main specs.
If the sync process unintentionally changes the intended meaning, omits requirements, or introduces semantic inconsistencies, these issues might go unnoticed without additional verification.
What I've found
Based on the official documentation:
My understanding is that OpenSpec provides structural validation and checks whether delta operations are correctly applied. However, it's unclear how thoroughly these checks verify semantic consistency between the intended changes and the resulting main specs.
Tradeoff: Archive inside the PR
The [team workflow guide — When to archive](https://github.com/Fission-AI/OpenSpec/blob/main/docs/team-workflow.md#when-to-archive) also describes an alternative:
I understand that archiving inside the PR allows reviewers to validate the final main specs before merging, but I'm not entirely sure what specific review challenges the term "noisier" refers to.
For example, does it mean duplicated spec content, additional file changes caused by archiving, or the extra effort required to review both code changes and the resulting main specs?
This seems to be a tradeoff between review completeness and review complexity, but I'd like to better understand the reasoning behind the recommendation.
Questions
/opsx:archiveverify semantic correctness beyond structural and delta-operation checks?Our goal is to follow the recommended workflow while keeping
openspec/specs/a reliable source of truth, without introducing unnecessary review overhead.I'd appreciate the team's perspective on the intended workflow and best practices.
All reactions