OpenSpec Rejected Proposals: A Decision Memory Convention

OpenSpec rejected proposals lack a built-in decision memory, meaning there is no inherent way to identify if an idea was previously investigated and declined. The /opsx:archive feature, designed to record shipped changes, does not provide an equivalent rejection counterpart. This absence becomes significant in brownfield systems with limited contributors and agents that revisit architectural questions periodically.

During a discussion with OpenSpec maintainers, they agreed that this gap in functionality should be addressed. The guide explores the consequences of relying solely on /opsx:archive, the debate that transpired within OpenSpec's issue tracker, and a straightforward decision.md pattern that can be implemented without waiting for core support.

Archiving a change that was not built seems to work, as the folder is moved out of active lists. However, the archived change lacks status information, making it visually indistinguishable from shipped changes among dozens of shipped modifications. This ambiguity fails to provide any indication to an agent or teammate scanning the archive, requiring manual inspection of each proposal folder and its contents.

The default workflow does not prompt agents to search the archive before initiating a new proposal. /opsx:propose drafts are derived from the current request and codebase state alone, without cross-referencing prior rejected changes unless explicitly instructed to do so. If a rejected change contains draft delta specs and it is archived using the standard method, /opsx:archive attempts to synchronize those deltas into openspec/specs/.

Accepting this can unintentionally integrate the corrupted, non-constructed specifications into the main system, affecting the record of what the system truly does.

Despite being designed to be lightweight by default, OpenSpec allows users to define their own conventions for handling rejections. The CLI offers the --skip-specs flag to archive a change without syncing any delta specs. This enables clean exclusion of non-constructed delta specs from the canonical system record.

Ultimately, OpenSpec's maintainers decided against providing first-class Architecture Decision Record (ADR) support in the core tool. Instead, they encouraged the development of community schemas and repository-level conventions to manage such workflows. A designated schema, created by OpenSpec technical advisor Hari Krishnan, includes an additional fifth artifact, design.md, which preserves reasoning behind decisions even after archiving.

Alternatively, a repository-level decision.md file and a naming convention can be manually implemented to maintain this crucial documentation.