20 KiB
Adapter Failure Discipline v1 🧭
First formal discipline layer for preventing adapter drift, false confidence, and premature repair
Quick links:
- Back to Atlas landing page
- Back to Atlas Hub
- Open Atlas-to-AI Adapter v1
- Open Adapter Runtime Modes v1
- Open Canonical Casebook v1
- Open Patch Governance v1
- Open Validation Basis v1
If the Atlas-to-AI Adapter is the layer that makes Atlas routing usable inside real AI interaction, this page is the layer that keeps that adapter from quietly becoming sloppy, overconfident, or overhelpful.
This document does not exist to make the adapter sound strict.
It exists to make sure the adapter stays structurally honest under pressure.
Short version:
route first
explain the cut
keep confidence honest
preview repair with restraint
do not let mode flexibility become routing drift
That is the job of this file.
Quick start 🚀
I am new to the adapter layer
Use this path:
- read Atlas-to-AI Adapter v1
- read Adapter Runtime Modes v1
- read this page
- then inspect Canonical Casebook v1
- then inspect Patch Governance v1
I already know the adapter and want the shortest route
Start here:
- this README
- Section 4, the ten core rules
- Section 6, how the rules behave across runtime modes
- Section 7 and Section 8, what to do when evidence is weak or the case is difficult
Shortest possible reading:
the adapter must remain a disciplined Atlas interface,
not a smooth-sounding shortcut machine
What this page is protecting 🛡️
This page protects the Atlas adapter from four kinds of failure:
-
routing drift
the adapter starts naming families loosely instead of cutting by broken invariant -
confidence abuse
the adapter sounds certain when evidence is weak -
repair overreach
the adapter rushes into fix language before the route is stable -
mode drift
the adapter changes behavior across modes in ways that silently damage structure
That is the real scope.
This file is not just a style guide.
It is the first formal discipline layer for keeping the adapter useful, honest, and stable.
Why this document exists
A routing adapter can fail even when the underlying Atlas is good.
That happens because adapters live in a messy environment.
They are exposed to:
- shorter contexts
- mixed user intent
- prompt compression
- overhelpful narration
- weak evidence
- token pressure
- mode confusion
- pressure to give action before the cut is clear
Without explicit discipline, the adapter can slowly degrade into behaviors like:
- vague family labeling
- fake certainty
- overcompressed reasoning
- misrepair overreach
- silent boundary drift
- generic outputs that no longer reflect Atlas structure
That is exactly what this page exists to prevent.
The Atlas adapter should not merely sound structured.
It should actually remain structurally disciplined.
Core principle ✨
The most important principle is this:
adapter usefulness depends on disciplined restraint,
not on maximum verbosity and not on maximum confidence
The adapter becomes better not when it says more.
It becomes better when it preserves the right structure under pressure.
That means the adapter must resist several temptations:
- saying too much
- pretending to know too much
- collapsing neighboring families
- giving repair advice too early
- hiding uncertainty to look clean
This file defines the rules that resist those temptations.
What adapter failure means here
Adapter failure does not only mean a technical crash.
In this system, adapter failure includes any behavior that causes the routing layer to stop acting like a reliable Atlas interface.
That includes failures such as:
- wrong primary-family assignment under avoidable conditions
- weak why-primary-not-secondary explanation
- invisible broken invariant
- unjustified confidence inflation
- repair preview that outruns routing evidence
- overloading outputs with irrelevant explanation
- dropping required fields in compact settings
- silently changing behavior across modes
So when this document says failure, it means both:
- structural output failure
- behavioral routing failure
That is the correct scope.
Adapter failure quick map 🗂️
| Failure region | What goes wrong | Typical symptom |
|---|---|---|
| Routing drift | the adapter stops cutting by invariant | labels feel plausible but weak |
| Confidence abuse | the adapter sounds stronger than the evidence | polished certainty on unstable routing |
| Repair overreach | the adapter moves into fix language too early | first move sounds like full closure |
| Mode drift | runtime modes stop preserving the same discipline core | compact, teaching, or repair mode silently mutates structure |
This map is useful because it lets reviewers inspect adapter behavior faster before diving into the full rule set.
The ten core failure-discipline rules 📌
The current first formal adapter release should preserve the following ten core rules.
Rule 1
Route first, then repair
The adapter must always perform routing before previewing repair.
That means:
- identify the primary family first
- identify the secondary family second
- explain why the primary cut wins
- identify the broken invariant
- only then expose fix-surface direction
Even in Repair-First Preview Mode, the adapter must not reverse this order.
Why this rule matters:
Many bad outputs happen when the system tries to be helpful too early.
That produces fake repair confidence on top of a weak cut.
The adapter must resist that.
Rule 2
Primary family must correspond to a real broken invariant
A family label without a broken invariant is not enough.
The adapter must not assign a primary family merely because:
- the topic sounds related
- the wording resembles a familiar case
- the user used family-like vocabulary
- a nearby exemplar seems emotionally similar
The primary family must correspond to the best current reading of the main broken invariant.
Why this rule matters:
Without this rule, routing becomes cosmetic.
With this rule, routing remains structural.
Rule 3
Secondary family must represent real neighboring pressure, not filler
The adapter must not use the secondary family field as decoration.
A secondary family should only appear when there is genuine boundary pressure or adjacency worth naming.
Bad secondary-family behavior includes:
- adding a secondary family just to sound nuanced
- naming a neighboring family without explaining the cut
- listing a weak neighbor that is not actually under pressure
Why this rule matters:
If secondary family becomes filler, boundary teaching collapses and routing trust drops.
Rule 4
Why-primary-not-secondary must remain explicit
The adapter must preserve an explicit explanation of why the primary cut wins.
This explanation may be shorter in Compact Routing Mode, but it must remain recoverable.
The adapter must not replace it with:
- vague family summaries
- generic reasoning language
- empty labels like “best fit”
- style-only confidence phrasing
Why this rule matters:
The Atlas is not just about naming where something goes.
It is about cutting correctly.
If the cut cannot be explained, the route is too weak.
Rule 5
Ambiguous must not be used lazily
The ambiguous signal is important, but dangerous.
The adapter must not mark a case ambiguous simply because:
- the case is hard
- the case is abstract
- the model feels uncertain
- multiple families are nearby in topic language
A case should be marked ambiguous only when the current evidence really does not justify a stronger primary reading yet.
Why this rule matters:
If ambiguous becomes a lazy escape hatch, the adapter stops being useful exactly where the Atlas is most valuable.
Rule 6
No-fit must not be used as a shortcut for effort failure
The no_fit signal is even more sensitive.
The adapter must not trigger no-fit because:
- the case is unusual
- the case is cross-domain
- the model did not reason deeply enough
- the prompt is short
- the answer space is uncomfortable
No-fit should be reserved for cases where the adapter has real reason to think the current Atlas genuinely lacks a stable fit.
Why this rule matters:
If no-fit is opened too easily, the adapter will falsely suggest core weakness where there may only be insufficient reading effort.
Rule 7
Confidence must follow evidence, not style
The adapter must not output strong confidence when evidence is weak.
This means confidence should depend on things like:
- clarity of the case
- stability of the family cut
- clarity of the broken invariant
- strength of neighboring-family separation
- support from known case patterns or exemplars
Confidence must not depend on:
- how fluent the output sounds
- how elegant the explanation is
- how familiar the vocabulary appears
Why this rule matters:
Confident nonsense is more dangerous than hesitant structure.
Rule 8
Overlay signals must not silently become primary-family replacements
If overlay concepts are used, they must remain overlays.
The adapter must not allow overlay-like signals to replace the family cut.
For example, the adapter must resist patterns like:
- treating visibility language as if it replaces F5 routing logic
- treating security language as if it replaces the family structure
- treating local layout markers as if they erase the need for a real primary family cut
Why this rule matters:
Overlays are useful only when they remain secondary markers.
If they start replacing family routing, the system flattens.
Rule 9
Exemplars may support the cut, but must not replace the cut
The adapter may use exemplars, casebook patterns, and boundary examples.
But it must not behave as if:
- “this looks like a famous example”
is enough to justify routing.
Exemplars should support:
- comparison
- contrast
- teaching
- stronger confidence where appropriate
They should not replace actual case reading.
Why this rule matters:
If the adapter starts matching cases by vibe rather than by structure, it becomes fragile very quickly.
Rule 10
Patch changes must not silently rewrite adapter behavior
Later improvements to the adapter are allowed.
But they must happen through explicit patching.
The adapter must not drift through hidden changes such as:
- changing required fields without saying so
- changing mode behavior without version note
- changing confidence discipline without explanation
- changing compact-mode minimum outputs without policy visibility
Why this rule matters:
The adapter is part of the Atlas control surface.
Silent behavioral mutation makes the whole system harder to trust.
The four main adapter failure regions 🧩
The ten rules above can be grouped into four major adapter-failure regions.
These are not top-level Atlas families.
They are adapter failure patterns.
A. Routing drift
Examples:
- wrong primary cut
- decorative secondary cut
- vague why-primary explanation
- family selection by topic similarity instead of invariant
B. Confidence abuse
Examples:
- high confidence on weak evidence
- ambiguity used lazily
- no-fit used as escape
- polished wording hiding weak structure
C. Repair overreach
Examples:
- repair advice before route clarity
- first repair move phrased like full solution
- misrepair risk ignored
- action preview outrunning routing evidence
D. Mode drift
Examples:
- Strict mode becoming too hard-edged without evidence
- Teaching mode becoming too loose
- Repair-First mode becoming overpromising
- Compact mode dropping required structure
These four regions are useful because they help reviewers inspect adapter outputs more clearly.
How failure discipline applies across modes ⚙️
The same discipline rules apply across all runtime modes, but different modes create different pressure points.
Strict Routing Mode
Main risk:
- false hardness
- compressed but unjustified certainty
- overclean outputs that hide weak evidence
Most important protection:
- confidence discipline
- explicit why-primary-not-secondary
- broken invariant visibility
Teaching Mode
Main risk:
- explanation inflation
- drifting into essay mode
- replacing routing with commentary
Most important protection:
- preserve structured fields
- keep boundary explanation tied to actual case
- keep misroute teaching compact and relevant
Repair-First Preview Mode
Main risk:
- overpromising repair closure
- sounding like a completed diagnosis engine
- jumping to fix before route stability
Most important protection:
- route first
- first move only
- explicit misrepair risk
- no fake closure language
Compact Routing Mode
Main risk:
- field dropping
- false simplicity
- overcompressed reasoning
- missing uncertainty signals
Most important protection:
- preserve minimum required fields
- preserve confidence and evidence_sufficiency
- preserve why-primary-not-secondary even in short form
What should happen when evidence is weak 🔍
Weak evidence is normal.
The adapter must be able to behave well under it.
When evidence is weak, the adapter should:
- lower confidence
- state what remains unclear
- keep the current best cut explicit
- avoid pretending that ambiguity equals uselessness
- avoid pretending that weak evidence equals no-fit
- avoid expanding repair advice beyond first safe direction
This is one of the most important practical behaviors in the whole adapter system.
A good adapter does not panic when evidence is weak.
It becomes more honest.
What should happen when a case is difficult 🧠
Difficult cases are where the adapter earns trust.
When a case is difficult, the adapter should:
- preserve family-level discipline
- name the strongest current cut
- name the strongest neighbor if relevant
- keep broken invariant central
- keep uncertainty visible where justified
- resist dramatic overreach
- preserve route-first logic
It should not react by becoming:
- vague
- overconfident
- overphilosophical
- structurally empty
Difficult cases are not permission to abandon form.
Why this matters for demos and product surfaces 🪟
The adapter will often be seen through:
- demos
- notebooks
- route-and-preview tools
- support flows
- public examples
That means failure discipline is also part of the product surface.
A demo that looks impressive but violates adapter discipline can actually weaken trust.
For product-facing use, the adapter must especially resist:
- polished but ungrounded certainty
- route labels without broken invariant
- repair wording that sounds more solved than it really is
- mode confusion between teaching and repair preview
Product polish must not outrun structural honesty.
That is the real rule.
Relationship to casebook and repair layer 🔗
This document should be read together with the casebook and fix layer, but not confused with them.
Casebook gives:
- good examples
- boundary teaching
- repair teaching
- wrong-route and misrepair exemplars
Fix layer gives:
- first repair grammar
- misrepair warnings
- bridge into deeper WFGY exploration
Failure discipline gives:
- behavioral rules that stop the adapter from misusing both of the above
That distinction matters.
This file is not content.
It is conduct.
Relationship to patch governance 📎
Adapter failure discipline must remain patchable, but not casually mutable.
Future work may refine:
- confidence thresholds
- mode-specific output discipline
- exemplar-use rules
- compact-mode minimum fields
- ambiguity and no-fit handling language
But these refinements must happen through explicit patching.
Why?
Because if adapter discipline changes silently, downstream users lose track of what the adapter is supposed to protect.
That damages system trust.
What this document does not claim 🚧
This document does not claim that:
- adapter failure can be eliminated completely
- every future edge case is already covered by these rules
- the adapter is now a perfect autonomous routing system
- mode selection alone guarantees good outputs
- repair preview is already equivalent to repair execution
This document claims only that:
the first formal Atlas adapter release now has an explicit failure-discipline layer strong enough to prevent the most damaging forms of routing drift, confidence abuse, repair overreach, and mode confusion
That is the strongest honest version.
Recommended official wording 📣
When you need a short adapter-discipline statement for a new window, support page, or collaboration thread, use wording like this:
The Atlas adapter is governed by an explicit failure-discipline layer.
It must preserve route-first behavior, broken-invariant visibility, honest confidence, explicit why-primary-not-secondary reasoning, and restrained first-move repair preview.
Adapter flexibility does not override structural discipline.
This wording is strong, accurate, and reusable.
Next steps ✨
After this page, most readers continue with:
- Open Atlas-to-AI Adapter v1
- Open Adapter Runtime Modes v1
- Open Canonical Casebook v1
- Open Patch Governance v1
If you want the broader Atlas surface:
One-line status 🌍
This document defines the formal discipline rules that keep the Atlas adapter from drifting into vague routing, false confidence, premature repair, or unstable mode behavior.
Closing note
A routing adapter does not fail only when it crashes.
It also fails when it becomes too smooth, too vague, too confident, or too eager to help.
That is why discipline matters.
A good adapter is not only informative.
It is restrained in the right places.