To preserve why an OpenSpec proposal was rejected, keep the investigation with archived work and add a short decision.md that states the outcome, reasons, alternatives and conditions for reconsideration. This is a repository convention—not a built-in OpenSpec artifact or a universal lifecycle rule. The goal is to keep the rejected idea and its reasoning discoverable without making its unshipped behavior look like current product behavior.
What belongs in an OpenSpec decision record?
Keep the original proposal as the record of context and options considered. Add a separate decision.md to make the final disposition unmistakable. A practical outline is:
As an Amazon Associate I earn from qualifying purchases.
# Decision
Status: Rejected
## Decision
State what was rejected and what the team will continue doing instead.
## Reasons
Record the criteria, constraints and trade-offs behind the outcome.
## Alternatives considered
Summarize realistic options the team considered.
## Revisit conditions
Name specific evidence or changed constraints that would make reconsideration worthwhile.This outline is a suggested local pattern, not an official OpenSpec template. Adapt the filename and location to the repository’s conventions. The important part is that a future contributor can tell what happened, why, what else was considered, and what would need to change for the question to be reopened.
Recommended Free Tools
Where should rejected OpenSpec changes go?
One workable convention is to retain the rejected investigation under the repository’s archive alongside completed change work, with decision.md next to its proposal. That makes the disposition available where contributors already look for change history. The archive location and filename are choices for the repository, not requirements imposed by OpenSpec.
#1 Best Overall
Keep this record distinct from the current specifications. OpenSpec’s documented workflow uses proposals, specs, design and tasks as change artifacts; its schema instructions distinguish a behavior contract from an implementation plan, and its conventions describe changes as specification deltas that are applied during archive. See the OpenSpec schema documentation and OpenSpec conventions specification. A rejected proposal’s hypothetical behavior should not be added to current specs as if it had shipped.
How is rejection different from acceptance?
In the documented workflow, an accepted change can be archived and its specification deltas applied to the current specifications. Rejection has a different outcome: preserve the reasoning and investigation, but do not apply an unaccepted behavioral delta as current truth. The available official materials describe the change workflow, but do not define a universal rejected-change lifecycle or a built-in decision.md artifact.
Proposal practices can also be repository-specific. One repository README structures proposals around Context, Why, What Changes and Impact, and says proposal use is guided by author judgment rather than a gate. That is an example of local policy, not an OpenSpec-wide requirement. See the repository-specific README.
What makes the record useful to the next contributor?
- Clear status: Put “Rejected” near the top so the proposal cannot be mistaken for approved work.
- Decision and rationale: State what the team chose instead, then explain the criteria and trade-offs that led there.
- Real alternatives: Capture options that were seriously considered, not an exhaustive list of imaginable designs.
- Revisit conditions: Name evidence, constraints or circumstances that would justify a new discussion.
- Consistent placement: Store the record where the repository’s contributors expect to find archived change history.
For example, an illustrative rejected proposal might explore moving a service boundary, then record tighter compile-time coupling and an implicit persistence contract as reasons against it. Those are example-specific considerations, not general evidence about service boundaries or OpenSpec projects.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.How should a repository choose its approach?
Compare the available options against the repository’s own workflow rather than treating one layout as mandatory:
| Approach | What it preserves | Trade-off |
|---|---|---|
| Proposal only | Context and the original case for the change. | The final rejection and its rationale may be difficult to distinguish from an unresolved proposal. |
Proposal plus decision.md |
Original context alongside a scan-friendly outcome, rationale, alternatives and revisit conditions. | Adds a small local convention contributors must follow consistently. |
| Repository-specific decision record | The same decision history using a filename or location that matches existing policy. | Discoverability depends on documenting and applying that policy consistently. |
Whichever approach you choose, make the rejected status explicit and keep rejected behavior out of current specifications. The available documentation does not establish that CI or openspec validate requires decision.md.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitches
