chemenu/instructions/subtype-templates.md

type, name, description, manual

type	name	description	manual
types/instruction.md	subtype-templates	Interview the corpus and the user for page skeletons per subtype - find subtypes whose pages systematically depart from their type's template, propose a types/<type>.<value>.md for each, and write the ones the user accepts.	true

Find the subtypes that need a page skeleton of their own

A page type carries one ## Template block for every value of its subtype field, and for most values that is enough. Where a subtype needs a different page shape - a person is not described by a version and a repository, a decision wants its context, alternatives and consequences - authors rebuild every scaffolded page by hand, and the corpus shows it. A subtype template, types/<type>.<value>.md, gives that subtype its own skeleton: wikitool new takes it instead of the block whenever the page's subtype field holds <value>. The file's shape and the checks on it are types/type-spec.md § "Anatomy of a type".

This instruction is the interview that decides which subtypes get one. It reads the pages first and proposes from them, because a template written ahead of the material is a guess every later page is scaffolded into.

When to run

• The user asks for it, by name or by describing the symptom: pages of one kind keep being rebuilt after wikitool new.
• After evolve-subtypes.md added a value and its pages have accumulated.
• After an upgrade delivered a subtype template as .template beside a type already adopted, and the user wants to know whether to take it.

Not for changing the ## Template block every subtype shares - that is an edit to the type-spec itself. Not for adding a subtype value - that is evolve-subtypes.md.

Steps

1. List what there is to examine. Every type-spec with a subtype_field:, every value its schema allows, and which skeleton each value scaffolds today:

   tools/wikitool types list
   tools/wikitool types describe <type>
   ls types/
   

   A value scaffolds from types/<type>.<value>.md if that file exists, otherwise from the type-spec's ## Template block.

2. Hold each value's pages against the skeleton they were scaffolded from. Find them and read their ## headings:

   tools/wikitool search --field <subtype_field>=<value>
   

   What counts is a departure several pages share: the same template section emptied or deleted, the same section added under the same or an equivalent name, the same section replaced by another. One page's own extra section is that page's business.

3. Apply the admission threshold of evolve-subtypes.md: at least three pages of one subtype departing the same way. A template is admitted after the material has shown its shape, never in expectation of it. A smaller count is only ever an explicit exception the user names, never a reason to lower the threshold.

4. Offer a shipped template as the starting point where one is lying ready. A types/<type>.<value>.md.template that was never adopted is the stack's proposal for that subtype. Compare it with what the pages actually do, and propose it unchanged, adapted, or not at all.

5. Put each candidate to the user, one at a time: which pages, what they share, and a draft of the template in the KB language (kb/CONVENTIONS.md language:) - the same variables and filters the ## Template block uses (types/type-spec.md § "Template variables"), no frontmatter, no fence, no tool-owned section. The user decides per candidate: accept, change, or reject.

6. Write each accepted template, then check it:

   tools/wikitool dist adopt types/<type>.<value>.md.template   # only where step 4 took the shipped one unchanged
   tools/wikitool docs verify
   

   Otherwise write types/<type>.<value>.md directly. docs verify refuses a file whose type has no subtype_field:, whose value the schema does not allow, or which carries frontmatter.

7. Leave the existing pages as they are. A template acts only on the next wikitool new; reshaping existing pages to match it is ordinary page editing, decided per page, and not part of this procedure.

Decision points

• The departures differ from page to page? Then no template is warranted: a skeleton that fits none of the pages well is not better than the one they already rebuild.
• All subtypes of a type depart the same way? The ## Template block itself is wrong, and editing it is the fix - not one subtype template per value.
• The value is guidance? It cannot have a template: types/<type>.guidance.md is always the type's guidance file. Rename the value instead, through evolve-subtypes.md.

Scope

Covers every page type that declares subtype_field: - in the shipped specs entity, concept, source and project. A type without one, such as comparison, has a single skeleton by construction. Does not move, rename or rewrite a page.