| name | resolve-spec-conflict |
| description | Resolve a conflict between two functional specs in a ***plain spec file. Use when conformance tests for a previously passing spec start failing after a new spec is rendered, or when a potential conflict is detected while adding a new functional spec (via `add-functional-spec` or `add-functional-specs`). |
Resolve Spec Conflict
Always use the skill load-plain-reference to retrieve the ***plain syntax rules — but only if you haven't done so yet.
When This Applies
A conflict exists (or is suspected) when:
- Conformance tests for a previously passing functional spec begin to fail after a new spec is rendered.
- A new spec being added (via the
add-functional-spec or add-functional-specs skill) appears to contradict an existing spec.
- Two specs make incompatible assertions about the same behavior, data, or state.
Workflow
Step 1: Identify the Conflicting Pair
Read the .plain file and pinpoint the two specs in tension. If the conflict was detected via a conformance test failure, also read the failing test and the generated implementation in plain_modules/ to understand what behavior changed.
Step 2: Diagnose the Root Cause
There are three possible outcomes — determine which one applies before making changes:
| Outcome | Symptom | Fix |
|---|
| Implementation is incorrect | Generated code doesn't match the spec's intent. The specs themselves are fine. | Clarify the ambiguous spec so the renderer interprets it correctly. Re-render. |
| Conformance tests are incorrect | The tests don't accurately verify the spec. The implementation is actually correct. | Adjust ***test reqs*** or ***acceptance tests*** to guide better test generation. Re-render. |
| Requirements truly conflict | The two specs are inherently contradictory — no implementation can satisfy both. | One or both specs must be revised. See Step 3. |
How to diagnose:
- Read both functional specs carefully. Can a single implementation satisfy both simultaneously?
- If yes → the specs are compatible; the issue is ambiguity (outcome 1) or bad tests (outcome 2).
- If no → the requirements truly conflict (outcome 3).
Step 3: Resolve the Conflict
When the requirements truly conflict, choose a resolution strategy:
Strategy A: Add detail to disambiguate. Often the specs aren't contradictory — they're just ambiguous enough that the renderer picks a conflicting interpretation. Adding explicit context to one or both specs eliminates the ambiguity.
Before (ambiguous):
***functional specs***
- All :Resource: items are returned.
- Only active :Resource: items are returned.
After (disambiguated):
***functional specs***
- All :Resource: items are returned when no filter is specified.
- When the "active" filter is specified, only active :Resource: items are returned.
Strategy B: Revise the newer spec. If the new spec introduced the conflict, rewrite it to be compatible with the established behavior from earlier specs.
Strategy C: Revise the older spec. If the older spec was under-specified and the new requirement reveals a better design, update the older spec. This is more disruptive — all conformance tests for that spec and everything after it may need re-rendering.
Strategy D: Merge into one spec. If the two specs describe overlapping behavior, combine them into a single, clear spec. Remove the redundant one. Be mindful of the 200 LOC limit.
Step 4: Validate the Resolution
After editing:
- Re-read the full
***functional specs*** section to confirm no new conflicts were introduced.
- Check that any revised spec still respects the 200 LOC limit.
- Check that chronological ordering still makes sense (earlier specs should not depend on later ones).
- If resolving via test adjustments, verify the
***test reqs*** or ***acceptance tests*** changes are appropriate.
Prevention (for use during add-functional-spec / add-functional-specs)
Before adding a new spec, run through this quick conflict check:
- List every existing functional spec that touches the same
:Concepts: as the new spec.
- For each, ask: "Can a single implementation satisfy both this existing spec and the new one?"
- If any answer is "not obviously yes" — add explicit detail to the new spec to eliminate the ambiguity before inserting it.
Validation Checklist
