cc-os/plugins/os-vault/skills/design-template/SKILL.md

---
description: Design SecondBrain note-type templates and create new note types — the repeatable 4-step template-design process and the full new-type-creation lifecycle
---

Use this skill when designing or revising the structure of SecondBrain note types — either
designing a template for an existing type or introducing a brand-new type to the vault.

These templates govern notes that are injected into AI context mid-task, repeatedly, across
every project, indefinitely. Every section is a recurring token tax. The governing rule for
every decision in this skill:

> **The burden of proof is on inclusion. A section exists only if you can name a consumer who
> acts differently because it's there.**

This is the **injection-economics filter**. A section earns its place only if it pays for the
tokens it costs when injected. Sections that fail the filter are **removed, not commented out**.

## Routing — pick the workflow

Decide by context:

- **Template design** — you have a note type (existing or just-defined) and need to design or
  revise its template. → Use the **4-step template-design process** below.
- **New-type creation** — the vault needs a type that doesn't exist yet. → Use the
  **new-type-creation lifecycle** below, which delegates to the template-design process for the
  template itself.

If unsure: if the type already exists in `vault-conventions.md`, you're doing template design.
If you're recognizing a gap and proposing a new type, you're doing new-type creation.

## Template design — the 4-step process

Run this for any note-type template, new or revised.

### 1. Model the consumers

Write down who reads this type and the one action each takes. Grab or construct one exemplar —
N=1, even synthetic, is enough; the process does not require a corpus.

### 2. Extract the minimal body shape

Name 2–4 body sections, ordered **action-first → why/when → caveats-last**. For each candidate
section, write one line:

> *[consumer] acts differently because this section is here.*

**No line = cut the section.** This is the injection-economics filter in practice. Add a subtype
variant only if a real variant needs a genuinely different core shape.

### 3. Draft the fillable skeleton

Assemble:

- the fixed frontmatter block (per the authoritative schema in `vault-conventions.md`),
- an H1,
- each section as a header with a one-line inline instruction (what goes here + target density),
- an abbreviated filled example showing the target density.

### 4. Dogfood and cut

Fill the template with the exemplar. Cut any empty or padded section; tighten any ambiguous
instruction; re-fill. **Done when the exemplar fills the template with no empty sections and no
padding.** This step catches paper-good/practice-ignored structure before it ships.

## New-type creation lifecycle

Adding a new type to the vault. Delegates to the template-design process above for the template
itself.

1. **Recognize the trigger.** What signals a type gap? The SessionEnd catch-all surfacing
   something that doesn't fit an existing type; repeated in-session workarounds for the same
   structural problem; N≥3 real instances exist that share structure.
2. **Collect N≥3 real examples** (or construct synthetic ones).
3. **Define the question frame** the type answers (the one-line "When I encounter X, what do I
   need?" question).
4. **Follow the template-design process** above to produce the template.
5. **Add the type definition to `vault-conventions.md`.**
6. **Create the template file in `_templates/`.**
7. **Author the first 2–3 notes** using the template.
8. **Dogfood critique** — the template already bakes this in via Step 4 of the design process.
9. **Refine based on findings.**

## Key design decisions

These are baked into the process above; keep them in mind when applying it.

- **Frontmatter and body serve different consumers.** Frontmatter (`summary` + tags) serves the
  **scanning human** and the **recall AI**. The body serves only two consumers: the **injected AI
  mid-task** and the **executing human**. Both want the actionable core up front; they differ only
  in how far they read. One artifact, progressive disclosure, different stopping points.
- **One shared spine, three type-specific body shapes.** Every template follows the same spine:
  frontmatter → H1 → actionable core → why/when → caveats. The three types (`convention`,
  `reference`, `howto`) differ only in their body shape on top of that spine.
- **Subtypes are body variants, never separate templates.** A subtype is a variant within a
  template's body, not its own template file. Add one only when a real variant needs a genuinely
  different core shape.

## Anti-patterns

The process must guard against these. Each is something the template-design steps actively
prevent:

- **Section inflation** — adding sections "for completeness." Every section must pass the
  injection-economics filter (Step 2). If no consumer acts differently, cut it.
- **Vague headers** — `## Notes`, `## Details`, and similar. A header must name what it holds.
- **Body duplicating frontmatter** — the body must not restate `summary` or tags. Frontmatter
  serves the scanning human and recall AI; the body serves the injected AI and executing human.
- **Paper-good / practice-ignored structure** — a template that looks clean but doesn't fill
  cleanly. Caught by the dogfood step (Step 4).
- **Convention stated without its boundary** — a convention note that gives the rule but not
  where it stops applying (the exceptions / anti-patterns).
- **Smuggling project narrative** — episodic, project-specific story content belongs in
  memsearch, not SecondBrain. Templates should make this hard to do.