Resolve Spec Conflict

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:

How to diagnose: 1. Read both functional specs carefully. Can a single implementation satisfy both simultaneously? 2. If yes → the specs are compatible; the issue is ambiguity (outcome 1) or bad tests (outcome 2). 3. 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):
- The system should return all :Resource: items.
- The system should return only active :Resource: items.

After (disambiguated):
- The system should return all :Resource: items when no filter is specified.
- When the "active" filter is specified, the system should return only active :Resource: items.

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: 1. Re-read the full ***functional specs*** section to confirm no new conflicts were introduced. 2. Check that any revised spec still respects the 200 LOC limit. 3. Check that chronological ordering still makes sense (earlier specs should not depend on later ones). 4. 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:

1. List every existing functional spec that touches the same :Concepts: as the new spec. 2. For each, ask: "Can a single implementation satisfy both this existing spec and the new one?" 3. 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 each imply ≤ 200 LOC
• [ ] No new conflicts introduced by the fix
• [ ] Chronological ordering preserved
• [ ] All referenced :Concepts: are still defined