E.8:4.2.1 - Recognition text and assurance text

Every canonical pattern SHALL stabilise one primary EntityOfConcern, relation record, or claim record early enough that a cold reader can tell what kind of thing the pattern is actually governing. If ordinary forms vary (note, sheet, guided UI, rendering, review aid), the text must make explicit which of those are merely presentation forms of one primary selected EntityOfConcern, relation, or claim and which would instead name a different act, process, work-result record, or governing companion. Recognition and assurance texts may refine that selected item differently, but they must not silently swap the central kind.

If a pattern uses a broad umbrella or head together with a narrower operative branch, the text must also make the stack explicit early enough for first reading: what the broad head names, what the current narrowed branch is, what primary EntityOfConcern, relation record, or claim record is actually in play, what exact action assertion and predicate are current, and what wider work or process remains outside the pattern. A qualifier alone does not restore that stack.

Under F.18 local-first naming, the canonical pair here is recognition text and assurance text. The earlier provisional recognition shell and assurance shell wording is retired. These names refer to two reading-order functions carried by existing sections or projections inside one pattern; they do not mint new authoritySourceRef targets, generic neighboring-pattern relations, publication-form or face kinds, publication-face kinds, or a second face family. Additional didactic scaffolding remains optional and is justified when the family is especially easy to misuse, easy to over-read, or hard to teach. The instruction needed for the pattern’s declared use is part of its substantive contribution under §4.2.1.1, not optional scaffolding.

The recognition text is the first-reading text. It is the part of the pattern that lets a cold working reader recognise the situation quickly enough to decide whether to keep reading. It should start from a subject-domain or practice moment before internal taxonomy whenever the pattern is meant to help real work rather than only internal canon maintenance. In practice it usually appears in an early Use this when line or equivalent opening, plus the upper parts of Problem frame, Problem, Solution, Consequences, and nearby worked slices. Its job is to make visible:

• what ordinary working situation this pattern is for;
• what goes wrong if the pattern is missed;
• what the pattern buys the reader in practice;
• when this is not the right pattern;
• what primary EntityOfConcern, relation record, or claim record is actually being kept stable;
• and, when technical terms must appear early, a pairwise plain gloss for each early FPF-governed technical term.

The assurance text is the second-reading text. It carries the heavier FPF-governed material that makes the pattern reviewable and auditable:

• declaration blocks and typed fields when those are part of the pattern’s declared conformance or boundary claim;
• representation ontology, EntityOfConcern discipline, or primary-EntityOfConcern discipline;
• any minimal modeling or mathematical lens that keeps the primary EntityOfConcern, relation record, or claim record stable;
• guidance or check material, invariants, admissibility, and stop or neighbouring-pattern conditions;
• SoTA-Echoing when it carries explanatory work;
• and the review hooks that let a broader or more consequential interpretation or use be checked explicitly.

The assurance text may sharpen, justify, and discipline the recognition text. It must not silently replace, strengthen, or universalize the claim that the recognition text made visible. If the recognition text says “this pattern helps with a bounded working situation”, the assurance text must not quietly turn that into an unbacked carrier claim, unbacked guarantee, or broader universality claim.

If a pattern claims universal or transdisciplinary status, that claim must already be visible in the recognition text. It is not enough for universality to appear only later in a guidance or check sheet, declaration block, or SoTA-Echoing rationale. A broad claim should therefore be demonstrated in the recognition text through heterogeneous reader or domain situations adequate to the claimed breadth. The separate three-domain minimum in A.8 applies to universal-core U-kind admission. When a compact matrix helps, F.16 is the preferred template for showing that breadth. If SoTA-Echoing carries an FPF-governed claim, the practical implication of those rows should be recoverable from the recognition text and case bank rather than remaining a late-only justification layer.

Additional didactic scaffolding helps readers with a particular interpretation or learning difficulty after the necessary instruction is present. Useful additions can include:

• at least one concrete source and resulting-publication slice in Archetypal Grounding when the pattern defines or constrains transforms or publication change;
• at least one boundary-heavy example or anti-example when nearby or companion patterns are easy to confuse;
• reviewer guidance that tells what to inspect first and which neighboring FPF pattern defines or constrains the failure mode and which project-side FPF kind and reference named by value carries the claim or effect;
• local mini-definitions or glossary material for recurring terms that would otherwise be recovered only from project context.

Pattern density is therefore not “more metadata” and not “longer tag lists”. It is the presence of enough recognition, assurance, and, when needed, extra didactic material that a reader can understand the pattern, apply it lightly in ordinary cases, and recognise when a heavier review profile is required.

E.8:4.2.1.1 - Provide enough explanation for the reader’s use without requiring a complete reading

Use this authoring move when the intended users differ in relevant preparation, when a complete account burdens a current application, or when a compact instruction leaves its selection, adaptation or combination unexplained. The useful result is a sufficient connected reading for the present use, with the fuller content and its actual suppliers still available for the uses the pattern promises.

Distinguish preparation from coldness and purpose. Under F.19, a cold intended reader lacks the author’s private context; that reader can be an expert. The plausible-reader test uses the knowledge and task the text reasonably presupposes. Under C.2.8, identify the useful structure to recover and the preparation, operations, help, access and effort budget that matter. Knowing the subject, knowing this framework’s distinctions and knowing how to change a particular Method are different capabilities. A model name or broad professional qualification does not establish them.

Keep the full contribution and the present reading distinct. Maintain the explanation needed for the declared uses in the pattern language and its genuine public suppliers. A body may rely on a common worked application or an already explained constituent Method when the contribution and usable return are clear. The reader need not load every such explanation for every use. A short problem–solution instruction can serve recall or a familiar application; its success does not establish that it supports learning, adaptation or combination. Canonical headings and additional words likewise do not establish sufficient content.

Construct the reading from the work the reader needs to accomplish:

1. Keep the receiving question fixed. Determine what the reader must recognize, infer, perform or change here. Use available evidence or explicit assumptions about relevant preparation. If a missing prerequisite changes the next explanation, expose it and provide the needed support or return. Do not silently raise the reader’s preparation or narrow the requested work to make an inadequate explanation appear sufficient.
2. Carry the connected instruction. Retain the operation with its necessary inputs, distinctions, conditions and use-changing reasons. Ordinary prior knowledge may supply a familiar notation or inference. The new synthesis, exceptional condition or relation being taught must be supplied by the publication or an identified available source, rather than invented by the reader. When several Methods work together, retain what connects their results and how constituent actions enact the encompassing work; independent reminder phrases do not explain that connection.
3. Choose what is needed now and what can be reached later. Keep a meaningful inference together. An applicability condition that changes the current action belongs with that action even when its derivation is elsewhere. Give a direct return to the fuller explanation and state the situation that calls for it: an unfamiliar operation, changed premise, disputed ground, or proposed adaptation, for example. A reader who cannot recognize such a condition needs enough explanation or assistance to recognize it before relying on the compact instruction. One sufficient reading path needs no additional version.
4. Compare the actual use and burden. Follow C.2.8, E.12 and F.19 for the appropriate recovery question and evidence. Keep the task, preparation, assistance and access conditions comparable; distinguish an expert walkthrough, an actual reading and an assisted retry. Include an affected changed case when the promised use includes adaptation. Consider navigation, source retrieval and reconstruction as well as the amount of text. Preserve a sufficient existing account when another form gives no worthwhile improvement.
5. Repair the missing contribution or the reading arrangement. Supply an omitted relation, make a consequential condition visible, explain a prerequisite or improve access to an actual supplier. If the required content cannot be used reliably within the present budget, change the support, work decomposition, reader allocation or budget. Leave the original unmet use explicit until it is supported. A lower-cost answer to a different question does not satisfy it.

Develop a missing instruction. Work through the promised use with a concrete input and the reader’s stated preparation. At every consequential inference, choice or action, ask what the reader has at that point and what the next result requires. Follow an unexplained requirement backward to its producer, then attempt the connection forward. Include a branch or a change of scale when the promised use depends on it. A jump from a source result to a conclusion, or from a constituent’s success to the whole’s success, is a candidate gap even when each sentence is clear.

Determine what is missing before rewriting. If the author performed an unreported interpretation, selection, conversion or coordination, recover how it was done and why its result was acceptable. Write the determining distinction and operation, show the intermediate result, and explain how the next operation uses it. For a judgement, expose the evidence and criteria that distinguish materially different answers; do not invent a mechanical rule where professional judgement remains necessary. A worked example should reveal the reusable reason for the step, not merely the author’s chosen answer.

If the operation is available elsewhere, supply a usable return to the explanation and make the required input and resulting contribution clear. Ordinary knowledge reasonably presupposed for this reader need not be retaught. If the operation itself is unknown or its necessary evidence, means or capability is unavailable, prose repair cannot provide it: develop the operation through the relevant subject Method, use C.39.RO for a missing reusable construction, or keep the exact use-changing gap explicit. The instruction “adapt the method” does not supply an adaptation being promised to the reader. If the complete explanation already exists but is lost in the reading arrangement, restore access and the conditions needed to choose it.

Recover the recurring problem–conditions–remedy relationship from the case. Separate what the reader must preserve from values or choices that change with another instance. Work through a consequential variation to expose that distinction, especially when the pattern promises adaptation or combination. Repeatable use need not give an identical output: changing valid inputs can rightly change the result. Where the claim is reproduction of a particular research result, specify the intended comparison and agreement conditions rather than substituting successful use of the general Method.

Continue through the promised result and its material returns, not just the first repaired sentence. Keep independent uses distinct when they need different contributions. Stop elaborating when the intended reader can obtain the necessary operations and connections under the stated preparation and access, or when an explicit unresolved contribution limits the claim. More elementary detail is unnecessary when it changes no declared use. Apply the connected F.19 reading to the resulting explanation and its actual public presentation; that wording judgement does not establish the Method’s subject-matter effectiveness.

Worked authoring repair. A draft says, “Convert the supplied dates to ISO format.” The author knows that supplier North guarantees month/day/year and supplier South guarantees day/month/year, and has a converter that is correct for a supplied date order. The intended reader can run that converter but cannot infer the order of 03/04/2026 from its characters. The first missing instruction is the source-to-order selection, not conversion syntax.

The author makes the supplier guarantees and their scope available with the instruction, retains the supplier identity for each row, derives the order from the applicable guarantee, and passes the row and order to the converter. North’s value becomes 2026-03-04; South’s becomes 2026-04-03. The public explanation now supplies the connection the author previously made privately. A compact reminder for experienced users can point to this explanation, but must not invite them to guess a missing order.

Now South changes to mixed orders without row-level information. The same reusable reasoning localizes the unsupported connection: North and the earlier qualified South files remain usable; ambiguous new South rows need trustworthy row-order information or correctly matched converted dates. Repeating the converter with both orders cannot choose between them. The author explains this boundary and the missing contribution instead of making the earlier rule unconditional. These are stipulated task conditions and a worked construction, not evidence that users have successfully learned the Method.

Divide a method account from pedagogical companions by the work each supplies. A pattern can state a Method adequately for competent readers while a pedagogical companion provides the fuller teaching needed by a less prepared audience. Completeness is relative to the declared use and genuine suppliers; it does not require every beginner explanation in the pattern body. The pattern’s contribution still includes its problem and frame, forces, operative distinctions and connections, conditions, grounds for important choices, and criteria and limits of the result. Keep or directly supply the worked and changed-condition reasoning that the declared use needs. A title list or imperative sequence is insufficient when a competent reader must invent why its steps connect.

A competent author of instruction should be able to reconstruct what must be learned and preserved from this method account and its named accessible suppliers. State relevant prerequisites rather than presupposing an unspecified “smart reader”. A reader may know the domain but not the framework, or know the framework but lack the subject skill. Competence in the subject Method also does not automatically supply competence in teaching it.

A companion may explain prerequisites, add analogies and more examples, arrange a progression of tasks, provide practice and feedback, and gradually remove assistance. It can also supply extensive derivations and worked applications to which the pattern returns where needed. Distinguish these additions from the subject Method’s essential rules. A new pedagogical Method is content in its own right, not merely a different publication form of the subject pattern. E.11.PFP:4.4 selects a support publication unit or a separately identified product when that boundary matters. Different audiences need not receive independent authoritative copies of the subject Method.

To choose the division, follow one intended use and one consequential variation. Identify the missing competence or explanation, then decide whether the repair supplies an unexpressed subject-method connection, a learning activity, or a better presentation of an existing explanation. Put the first with its method owner or genuine public supplier; put audience-specific acquisition with the companion and its pedagogical grounds; repair presentation where the content already exists. Keep an action-changing condition visible at the point where a user needs it. The route to a fuller explanation must be usable within the declared support arrangement. A companion that has not been written or cannot be obtained leaves that audience’s promised learning unsupported.

When the division is uncertain, ask a suitably prepared reader who lacks the author’s private context to construct a small piece of instruction for a named audience from only the published method account and its declared suppliers. The result should identify what the learner must be able to do, connect a worked case and practice task to those operations, and state how a consequential mistake or changed condition would be handled. Trace a consequential instruction back to its method grounds, an explicit pedagogical choice, or an acknowledged gap. There is no need to copy every source sentence into a trace table.

Inspect any necessary invention. Choosing a motivating example or a teaching sequence is normal pedagogical design. Inventing the method’s missing selection criterion, inference, transformation or coordination shows that the method account or its supplying explanation is insufficient for that use. Repair that omission at its owner; do not conceal it in a privately generated course. Conversely, failure to teach an unprepared learner from a compact competent-reader pattern alone does not establish such an omission when an adequate companion is explicitly part of the selected arrangement.

This construction probe establishes only what that reader could recover and design. It does not establish that the proposed teaching works, that a generated guide is correct, or that learners can perform independently. Test those claims with their actual audience, task and assistance conditions. E.4.PFAD:4.1.1 compares the cost and value of the resulting pattern, companion and short-use routes, including their change dependencies.

For human and AI readers. Different readers may need different amounts of explanation for the same operation; the same reader may need more when adapting it. For an AI use, distinguish all available publication content from the material actually supplied or reachable during the invocation, including the tools needed to obtain it. A successful reconstruction qualifies that use under those conditions. It does not show that another model, another context budget or an unassisted human can do the same. A human-learning result does not by itself establish an AI context-management effect.

Authoring examples. A portfolio-comparison pattern can keep its general Method concise while a directly named common application supplies the alternatives, complete small calculation and changed-condition cases. The shared application must actually contain that work. A reminder to reuse a previous evaluation instead needs the same-question and still-applicable-evidence conditions beside the instruction; leaving them only in a distant rationale permits an unsupported reuse. A reader altering a construction may need its invariant and why the composition preserves it, even when an experienced operator can execute the unchanged construction from a brief reminder. These are different reading needs, not reasons to publish a separate authoritative Method for each audience.

Use existing sections, examples and direct references to organize these paths. E.11 governs discovery; it does not replace the required explanation with an entry card. E.14 keeps practical use and assurance connected; it does not defer a condition needed before action. E.17.EFP governs faithfulness when selecting or expressing an account: a faithful partial expression can serve a bounded use, while changed claims or a narrower use need their own explicit treatment. No fixed number of reading levels, parallel versions, characters or model-specific editions is required.