Docs Add Missing Section

Add a Missing Section to a Reference Page

REQUIRED BACKGROUND: Use docs-writing-style for prose conventions and docs-mdoc-conventions for code block syntax throughout.

Overview

Data type reference pages follow a canonical structure (see below). When a section is entirely missing — not just thin, but absent — this skill inserts it at the correct position with full, publication-ready content.

Canonical Section Ordering

Reference pages follow this sequence:

1. Opening Definition (no ##, directly after frontmatter)
2. Motivation / Use Case (if applicable)
3. Installation (if applicable; top-level types only)
4. Construction / Creating Instances (required)
5. Predefined Instances (if applicable)
6. Core Operations (required)
7. Subtypes / Variants (if applicable)
8. Comparison (if applicable; always after Core Operations)
9. Advanced Usage (if applicable)
10. Integration (if applicable)
11. Running the Examples (if applicable)

Step 1 — Read and Map the Existing Document

Read the full target file. For each ## heading:

• Record the heading text and line number
• Map it to the canonical ordering above

Identify the gap: where should the new section appear?

• Find the last ## heading that appears before the new section's position (the insertion point's predecessor)
• Find the first ## heading that appears after the new section's position (the insertion point's successor)
• Note the line range where the new section will be inserted

Record the document's tone, example style, heading naming conventions, and code block style (these inform your writing).

Step 2 — Research the Missing Section Content

Delegate baseline research to the docs-research sub-skill using the /docs-research command. It covers:

• Core source files
• Supporting types
• Real-world patterns
• GitHub history

Then apply section-specific research supplements:

For Construction sections:

• Grep the source file for all public factory methods (apply, empty, from*, of, derived, etc.)
• Grep test files for construction patterns and edge cases
• Check the companion object thoroughly for all static factory methods

For Predefined Instances sections:

• Grep the source file for val.*: <TypeName> patterns (both in the type itself and companion object)
• Check for implicit instances in companion objects
• Search examples for which predefined instances are used most often

For Comparison sections:

• Identify the closest 2–5 alternatives (sibling types, similar APIs, competing designs)
• For each alternative, research: mutability model, performance characteristics, API surface, typical use cases
• Build a mental model of the dimensions on which they differ (e.g., laziness, performance, API breadth, immutability guarantees)

For Advanced Usage sections:

• Glob **/examples/**/*.scala for non-trivial patterns combining this type with others
• Search test suites for integration patterns, composition tricks, or non-obvious behaviors
• Check GitHub issues for "how do I..." questions indicating real-world advanced usage

For Motivation sections:

• Search GitHub history for issues titled "Why use X?" or "X vs Y"
• Find the first commit introducing the type — read the commit message
• Trace the design rationale via related discussions

Step 3 — Determine the Correct Insertion Point

Match the section type to its canonical position from Step 1:

Fallback heuristic: If the document has non-canonical heading names (e.g., "Creating Chunks" instead of "Construction"), treat them as their semantic equivalents:

• "Creating X" → Construction
• "Preconfigured Instances" → Predefined Instances
• "Usage Patterns" → Advanced Usage

Once you determine the position:

1. Find the line number of the preceding ## heading (last before insertion point)
2. Find the line number of the following ## heading (first after insertion point)
3. The new section will be inserted between these two headings

Step 4 — Write the Section

Mandatory: Before writing, invoke these sub-skills for background:

• /docs-writing-style — prose rules
• /docs-mdoc-conventions — code block rules

Each section type has a specific structural template covering subsection layout, table layout, and the minimal code-block pattern. Load references/section-patterns.md when you reach this step — it contains templates for:

• Construction (factory methods, apply, empty, from[B])
• Predefined Instances (table + example)
• Comparison (dimensions table + "Use X when… Use Y instead when…")
• Advanced Usage (2–4 realistic scenarios)
• Motivation (problem → naive approach → working solution)

Step 5 — Insert the Section into the Document

Using the Edit tool, replace the content between the predecessor and successor headings:

Insertion format:

• Exactly one blank line above the new ## heading
• The complete new section (all content including subsections)
• Exactly one blank line below the section's last line of content

After insertion, re-read ±10 lines around the insertion point to confirm natural flow with adjacent sections.

Step 6 — Verify Compliance and Compilation

Step 6a: Compliance Check

Run the compliance verification:

/docs-verify-compliance <path-to-doc.md>

This delegates to:

1. docs-check-compliance <path> docs-writing-style
2. docs-check-compliance <path> docs-mdoc-conventions
3. sbt "docs/mdoc --in <path>"

Fix any violations before proceeding.

Step 6b: Manual Mdoc Compilation

Run:

sbt "docs/mdoc --in <path-to-doc.md>"

Never use bare sbt docs/mdoc — it recompiles all documentation (~90 seconds).

Success criterion: The output contains zero [error] lines. Warnings are acceptable.

If errors appear: Fix them immediately and re-run the single-file mdoc command until zero errors.

Step 7 — Commit

Stage and commit the modified file:

git add <path-to-doc.md>
git commit -m "docs(<doc-stem>): add <section-name> section"

Replace:

• <doc-stem> with the reference doc's stem (e.g., chunk for docs/reference/chunk.md)
• <section-name> with the section name (e.g., comparison)

Example commit messages:

• docs(chunk): add comparison section
• docs(schema): add advanced usage section
• docs(into): add predefined instances section

Common Mistakes

Reused Skills

Verification Checklist

Before committing, walk through every item in the sibling CHECKLIST.md. It covers section selection, content quality, technical accuracy, mandatory compliance gates, cross-references, and commit hygiene.