codeplain-ai 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-specoradd-functional-specsskill) 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
- Root cause diagnosed (implementation / tests / true conflict)
- Resolution strategy chosen and applied
- Revised specs are language-agnostic
- Revised specs trimmed per
concise-specs.md— added disambiguation stays as short as it can be - Revised specs each imply ≤ 200 LOC
- No new conflicts introduced by the fix
- Chronological ordering preserved
- All referenced
:Concepts:are still defined