114 lines
5.6 KiB
Markdown
114 lines
5.6 KiB
Markdown
---
|
||
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.
|