Phase 4

Artifact Authoring

Formalize the retained patterns into the five CDS artifacts. Order matters — each artifact depends on decisions locked in the one before it.

Authoring order

Do not skip ahead

The rules bundle references specific subcategories values that must match component_type keys in the registry. The skill file references specific filenames that must exist in the taxonomy. Writing out of order produces broken references that the integrity check (Phase 5) will catch — but fixing them after the fact is slower than getting the upstream artifacts right first.

Step	Artifact	Depends on
4.1	`content_type_taxonomy.yaml / .json`	Pattern set document from Phase 3
4.2	`component_registry.yaml / .json`	Taxonomy (family, atom, assembly structure)
4.3	`procedure_terminology.yaml / .json`	Registry (component names to define as terms)
4.4	`{type}_rules_bundle.json`	Taxonomy, registry, terminology (all three must be stable)
4.5	`{type}-pattern_SKILL.md`	All four prior artifacts

"Stable enough" means the core structural decisions are made — it does not mean every field is complete. You can leave notes and TODOs in upstream artifacts, but the fields that downstream artifacts reference must be settled.

4.1 Taxonomy entry

Write one entry in content_type_taxonomy.yaml (and its .json twin) for each retained pattern. Follow the existing Procedure and KC Article entries as format templates — every field name and nesting level must match.

Decision to make first: does this content type have subtypes (like KC Types A–F) or is it a single pattern? If subtypes: one taxonomy entry per subtype, one shared skill file that routes to all of them via a classification decision tree.

Required fields per entry

Field	What to write
`name`	Formal CDS name (e.g. "KC Article — Type A (Multi-Cause Troubleshooter)")
`family`	Procedural / Conceptual / Reference / Structural / Hybrid
`purpose`	One sentence — what this type does for the reader
`customer_need`	One sentence — what the reader is trying to accomplish
`distinguishing_criteria`	One entry per adjacent content type: `vs_X: one sentence`
`classification_signals`	3–5 observable signals, in priority order
`assembly_configurations`	If the type has variants — name, description, control tag
`atom`	The independently navigable or reusable unit (one sentence)
`skill_ref`	Exact filename of the skill file you will write in step 4.5
`rules_bundle_ref`	Exact filename of the rules bundle you will write in step 4.4
`examples`	2–3 real published examples with titles and URLs

4.2 Component registry entries

For each structural component unique to the new content type, write an entry in component_registry.yaml and its .json twin.

Check existing components first

These generic components are already in the registry and should be reused rather than duplicated: title, introduction, section_title, section_intro_paragraph, prerequisite, code_example, troubleshooting_entry, code_block, link, placeholder, service_name, bulleted_list, related_information. Content-type-specific rules for these components go in your rules bundle's subcategories scope — not in a new registry entry.

Create a new entry only for components that are structurally distinct from existing ones (different composition, different reuse class, or different boundary conditions).

Required fields per entry

Field	What to write
`component_type`	snake_case unique key. Must match the `subcategories` value you'll use in the rules bundle: `component-level:{component_type}`
`scope`	`generic` / `{type}-specific`
`reuse_class`	`reusable` (same content verbatim on multiple pages) / `non-reusable` (page-unique)
`description`	1–3 sentences including explicit distinctions from similar components in other types
`boundary_conditions`	List — when is this the right component vs. an adjacent one?
`rules_ref`	`subcategories=component-level:{component_type}` — must resolve to ≥1 rule in the bundle. INT-02 checks this.

Write registry entries before the rules bundle

The registry entries define the subcategories scope values the rules bundle must populate. If you write the rules bundle first and get the component name wrong, INT-03 will catch it — but fixing it means updating both the bundle and the registry to agree.

4.3 Terminology entries

For each term that is either new to the CDS vocabulary or that has a different meaning in this content type than it does in existing types, add an entry to procedure_terminology.yaml (and its .json twin). This file is shared across all content types.

Required fields per entry

Field	What to write
`term`	The preferred form — exactly as authors and agents should use it
`scope`	Content type, component, component attribute, CDS schema, etc.
`definition`	Precise. If the term means something different elsewhere in CDS, state the distinction explicitly.
`prohibited`	List of legacy terms, informal alternates, and easy confusions — with parenthetical context explaining why each is prohibited
`note`	(Optional) Usage constraints or disambiguation for edge cases

When to add vs. annotate

Add a new entry when the term is genuinely new to the CDS vocabulary.
Add a note to the existing entry when this content type reuses a term that already has an entry but behaves slightly differently. Don't duplicate the entry.
Add a new entry with an explicit distinction when this content type uses a term that conflicts with an existing entry (e.g. KC's resolution as a component vs. the Procedure's expected_results as the equivalent). State both senses and which content type each belongs to.

4.4 Rules bundle

The rules bundle is the largest and most consequential artifact. Write it last among the first four, after the taxonomy, registry, and terminology are stable.

ID namespace

Establish a numeric range for this content type's rules. Do not reuse IDs from other bundles. Document the namespace in the bundle's metadata.id_namespace block (start and end values). INT-09 checks that all rule IDs are within range.

Current namespaces in use: Procedure = 68001–68125. KC Article = 124001–124208.

Rule authoring order

Write in subcategories order: doc-level rules first, then component-level rules grouped by component, then doc-level:classification rules last.

Required fields per rule

{
  "id":                   integer — unique in this bundle, within namespace,
  "severity":             300 | 400 | 500,
  "severity_reason":      "one sentence explaining the tier choice",
  "mitigation":           "Fix",
  "rule_category":        "ComponentCategory" | "ComponentRule",
  "subcategories":        "scope query matching a rules_ref in the registry",
  "rule":                 "the constraint — one sentence, imperative",
  "use":                  "RequiredElement" | "RequiredFormat" | "ProhibitedPattern"
                        | "ContentStructure" | "StylePattern" | "LengthLimit"
                        | "OrderingRule" | "Guidance",
  "content_types_applied_to": "YourContentTypeName",
  "confidential":         false,
  "examples":             ["positive example"],
  "negative_examples":    ["negative example"]
}

Severity calibration

Severity	Meaning	Use for
300	Requires content strategist sign-off to publish in violation	Rules where violating produces structurally wrong content: missing required section, wrong classification, broken assembly
400	Author's own call; no sign-off needed	The majority of rules. Important conventions that can be relaxed with judgment.
500	Suggestion only; never blocks	Readability metrics, best practices, anything where the correct answer is context-dependent

After writing the bundle, verify manually

Every subcategories value referencing component-level:{x} has a matching component_type in the registry
Every rules_ref in the registry resolves to ≥1 rule in the bundle
Every quality dimension in metadata.quality_scoring lists the actual rule IDs at sev ≤300 for that dimension

These are also checked automatically by integrity_check.py in Phase 5 — but catching them mentally during authoring is faster than running the script and iterating.

4.5 Skill file

The skill file is the last artifact to write. It depends on all four prior artifacts being stable.

Required structure

Match the structure of procedure-pattern_SKILL.md exactly:

YAML front matter: skill identity, pattern identity, rules_ref, human_only_sections, metadata (core + extension), assembly manifest, examples, additional_resources
Overview section — what the content type is, how it differs from similar types
Classification decision tree (if the type has subtypes) — full tree, key distinctions table, reclassification signals table
Shared assembly rules — rules that apply across all subtypes
Per-subtype assembly sections — when/title patterns/roles, numbered instructions, output structure template with annotated placeholders
Validation criteria checklist — shared checks + per-subtype checklists
Dependencies table + References table

Test every template against the rules bundle before finalizing

The output structure templates in the skill file must themselves satisfy the rules in the rules bundle. A template that omits a RequiredElement will cause every output that follows the template to fail that rule.

For each template: extract every component it contains, look up that component's rules_ref in the registry, find all RequiredElement and OrderingRule rules in the bundle for that subcategory, and verify the template satisfies each one in the correct position. This is the hardest class of defect to diagnose later — the evaluator correctly flags "known-good" output and it looks like an evaluator bug when it isn't.

Discovery: Phases 1–3 Testing & Feedback