frontmatter-generation

Frontmatter Generation SOP

This is a Standard Operating Procedure for analyzing markdown documents and generating accurate, semantic frontmatter.

Step 0: Load Configuration (ALWAYS FIRST)

Before analyzing ANY document, read these files in order:

1. Read schemas.yaml (in this skill directory)

   • Understand all 7 content-types (blog-post, research, client-project, meeting-notes, workshop-material, clipping, note)
   • Note required fields vs optional fields for each type
   • Understand location patterns for auto-detection

2. Read taxonomy.yaml (in this skill directory)

   • Load complete existing tag taxonomy (50+ tags)
   • Understand tag hierarchy (e.g., ai → rag, conversational-ai, ml)
   • Note naming conventions (kebab-case, max 3 words)

You now have the knowledge needed to analyze documents correctly.

Step 1: Deep Semantic Understanding

Read the FULL target document and answer these questions:

1. What is this document ACTUALLY about?

   • Not what the filename suggests
   • Not what the directory structure implies
   • What does the ACTUAL CONTENT communicate?
   • Read every section and understand the core purpose

2. What is the document's PURPOSE?

   • What does it DO?
   • What does it PRODUCE?
   • Who is it FOR?
   • What problem does it SOLVE?

3. What is the document's NATURE?

   • Is it instructional? Analytical? Extractive? Creative? Generative?
   • What methods/mechanics does it employ?
   • What domain/field does it operate in?
   • Is it a tool, example, explanation, or something else?

Critical Rule: Base your answers on ACTUAL CONTENT, not filename or structure.

Step 2: Content-Type Detection

Based on your semantic understanding AND the loaded schemas:

1. Which content-type matches this document?
   • Check location pattern first (path-based detection)
   • Verify it matches the document's actual nature
2. Identify required fields for this content-type
3. Note optional fields that might apply

Step 3: Tag Generation (Quality Over Quantity)

Based on your semantic understanding AND the loaded taxonomy:

1. Select 5-7 tags from EXISTING taxonomy

   • Each tag must accurately represent what this document IS and DOES
   • NOT what the filename suggests
   • NOT structural tags that don't match content

2. Tag Selection Criteria:

   • Does this tag match actual content? (not just directory structure or filename)
   • Would someone searching for this tag expect to find THIS document?
   • Is this tag more accurate than alternatives?
   • Is this tag a better choice than a generic alternative?

3. Strongly prefer existing taxonomy tags

   • Only add new tags when no existing tag accurately fits
   • Only when the concept is significant to the document

4. Quality Validation (CRITICAL):

   • Read tags back to yourself
   • Ask: "Do these accurately represent this document's content?"
   • Would I expect to find this document if I searched for each tag?
   • Are any tags generic or structure-based rather than content-based?

Examples of WRONG vs RIGHT:

• ❌ WRONG: "find_logical_fallacies" tagged with output/email, output/essay, domain/health
  • These are generic, don't match actual content (fallacy detection)
• ✅ CORRECT: "find_logical_fallacies" with logical-fallacies, critical-thinking, argumentation, analysis
  • These accurately describe what the document teaches

Step 4: Metadata Extraction

Following the schema for detected content-type, extract:

• title: Descriptive, accurate title reflecting actual content
• description: 1-2 sentence summary of what document IS and DOES
• tags: The 5-7 validated tags from Step 3
• [Other required fields per schema]: Depending on content-type

Special Rules for Fabric Patterns

When analyzing Fabric patterns:

• Read IDENTITY section to understand what the pattern is
• Read DESCRIPTION section to understand purpose
• Read OUTPUT section to see what it produces
• Extract outputs field: What pattern ACTUALLY produces (not structure, actual content type)
• Extract inputs: What it expects (read INPUT section)
• Extract domains: Field/industry based on ACTUAL content, not directory structure
• Extract complexity: low|medium|high based on logic complexity
• Extract mechanics: extraction|synthesis|analysis|critique|transformation (what it DOES)

Step 5: Quality Validation (BEFORE WRITING)

Before writing frontmatter, validate:

1. Do tags match actual semantic content? (not structure or filename)

   • Read each tag and ask: "Does this describe what this document actually teaches/does?"
   • Would searching for this tag surface this document?

2. Is description accurate and specific? (not generic)

   • Description should reflect actual content, not just structure

3. Are all required fields present for content-type?

   • Check against schema from Step 0

4. Is this better than automated pattern matching?

   • Should have meaningful tags that reflect semantic understanding
   • Should not be generic or based on filename/structure

If any answer is "no", REVISE before writing.

Examples

See the examples/ directory for properly formatted frontmatter by content-type.

Frontmatter Writing Rules

• Use YAML frontmatter format (triple dashes above and below)
• Use kebab-case for all keys and tag values
• Quote string values if they contain special characters
• List tags as an array: tags: [tag1, tag2, tag3]
• Never add frontmatter to files that already have valid frontmatter (update instead)

Common Mistakes to Avoid

❌ WRONG: Generic tags based on filename or structure

• output/email, domain/health, type/markdown

❌ WRONG: Too many tags (18 tags instead of 5-7)

• Reduces signal, increases noise

❌ WRONG: New tags that duplicate existing tags with different naming

• Check taxonomy first before creating new tags

✅ RIGHT: Semantic tags that describe actual document content

• logical-fallacies, critical-thinking, argumentation for fallacy detection pattern

✅ RIGHT: 5-7 tags that all directly relate to document purpose

✅ RIGHT: Tags from existing taxonomy when available