---
type: types/instruction.md
name: subtype-templates
description: 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.
manual: 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](../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](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](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:

   ```bash
   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:

   ```bash
   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](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](../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:**

   ```bash
   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](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.