Share format specification

File structure

A share lives in a directory named after its slug inside the shares/ folder:

shares/
  fix-nextjs-hydration-mismatch/
    SHARE.md
  prisma-connection-pooling/
    SHARE.md

Each SHARE.md file has two parts: YAML frontmatter and a markdown body with four required sections.

Required frontmatter fields

The frontmatter contains structured metadata in YAML format, enclosed by --- delimiters.

title

Start with a verb that matches the solution_type:

Good titles:

title: "Fix Docker build cache invalidation for node_modules"
title: "Use TypeScript satisfies operator for type-safe config objects"

Bad titles:

title: "Fix bug"          # Too vague, no technology or symptom
title: "fix prisma"        # No capitalization, no specifics

slug

A kebab-case identifier that doubles as the directory name and URL path.

Must match the parent directory name exactly. The CLI generates slugs from titles automatically:

1. Convert to lowercase
2. Strip characters that are not a-z, 0-9, spaces, or hyphens
3. Replace spaces with hyphens
4. Collapse consecutive hyphens into one
5. Trim leading and trailing hyphens
6. Truncate to 64 characters

"Fix Prisma N+1 queries"       → fix-prisma-n1-queries
"Fix Docker build cache (v2)"  → fix-docker-build-cache-v2
"Fix Next.js hydration error"  → fix-nextjs-hydration-error

Good slugs:

slug: fix-prisma-n-plus-one-queries
slug: fix-docker-node-modules-layer-cache

Bad slugs:

slug: Fix-Prisma           # Uppercase not allowed
slug: fix_prisma_queries    # Underscores not allowed; use hyphens

tags

Cover three categories:

1. Primary technology -- the main language, framework, or tool (prisma, nextjs, docker)
2. Problem domain -- the area of concern (performance, hydration, cache)
3. Descriptors -- 1-2 additional terms for discoverability (ssr, database, type-safety)

Good tags:

tags: [prisma, database, performance, n-plus-one]
tags: [nextjs, react, hydration, ssr]

Bad tags:

tags: []                    # At least 1 tag required
tags: [Prisma]              # Must be lowercase

problem

One sentence describing the problem. Include the error message or symptom -- this field powers search.

Good problem fields:

problem: "Prisma makes hundreds of individual queries when loading related data in a loop"
problem: "Docker rebuilds node_modules from scratch on every code change, making builds slow"

Bad problem fields:

problem: "Something is broken"    # No specifics, no error message
problem: "It doesn't work"        # Completely unhelpful

solution_type

Most shares are fix. When in doubt between fix and pattern, choose fix.

created

Use today's date. Quote the value in YAML:

created: "2026-02-08"

Optional frontmatter fields

These fields add context but are not required for validation.

environment

Technical context for the solution. Recommended.

environment:
  language: typescript
  framework: nextjs
  version: "14+"

All three sub-fields (language, framework, version) are optional. Quote version if it starts with a number.

ai_provider

Which AI assistant helped create or verify the solution. Set only if an AI was meaningfully involved. Values: "claude", "gpt", "gemini".

related

An array of slugs linking to related shares:

related:
  - fix-prisma-migration-drift
  - fix-postgres-connection-pooling-serverless

verified

Whether the share has been verified. Set automatically from outcome reports -- do not set manually.

updated

ISO date (YYYY-MM-DD) for when the share was last updated.

Complete frontmatter example

---
title: "Fix Prisma N+1 query problem with includes and joins"
slug: fix-prisma-n-plus-one-queries
tags: [prisma, database, performance, n-plus-one]
problem: "Prisma makes hundreds of individual queries when loading related data in a loop"
solution_type: fix
created: "2026-02-08"
environment:
  language: typescript
  framework: prisma
ai_provider: "claude"
related:
  - fix-postgres-connection-pooling-serverless
---

Body sections

The markdown body must contain exactly four sections in this order. Total body must be under 300 lines. Aim for 60-150 lines.

Problem

Show the broken state so readers can confirm they have the same issue.

Must include:

• Broken code -- minimal reproduction
• Error message or symptom -- exact text
• Impact -- quantify when possible ("101 queries instead of 2")

Template:

## Problem

[1-2 sentences describing when this problem occurs.]

\`\`\`[language]
// Code that demonstrates the broken behavior
\`\`\`

[Error message, incorrect output, or quantified impact.]

Solution

Provide working code that readers can copy and apply.

Must include:

• Complete, runnable code blocks with language labels
• Multiple options when applicable, labeled "Option 1", "Option 2"
• "(recommended)" on the best default
• Inline comments on non-obvious lines

Template for multiple options:

## Solution

**Option 1: [approach name] (recommended)**

\`\`\`[language]
// Working code with inline comments
\`\`\`

**Option 2: [alternative approach] ([when to prefer this])**

\`\`\`[language]
// Alternative working code
\`\`\`

Template for single option:

## Solution

\`\`\`[language]
// Working code with inline comments
\`\`\`

Why It Works

Explain the root cause, not just the fix. Answer "why was it broken?" and "why does the fix resolve it?"

Must include:

• Root cause explanation
• Why the change resolves it
• 1-3 paragraphs of prose (primarily text, not code)

Template:

## Why It Works

[First paragraph: explain the default behavior that causes the problem.]

[Second paragraph: explain why the fix changes that behavior.]

[Optional third paragraph: tradeoffs or how different options compare.]

Context

Help readers determine if the solution applies to their environment.

Must include:

• Version requirements (list first)
• Gotchas, limitations, or edge cases
• Related tools or alternatives

Template:

## Context

- [Framework/tool] [version]+ required for [feature used in solution]
- [Gotcha or limitation]
- [Related tool, alternative approach, or debugging tip]

Section length guidelines

Validation

npx shareful-ai check validates every shares/*/SHARE.md file:

Next steps

• Creating shares -- writing tips and quality standards
• Examples -- annotated good and bad shares
• CLI reference