Share format specification

File structure

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

Copyshares/
  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:

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

Bad titles:

Copytitle: "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

Copy"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:

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

Bad slugs:

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

tags

Cover three categories:

1. Primary technology
2. Problem domain
3. Descriptors

Good tags:

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

Bad tags:

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

problem

One sentence describing the problem. Include the error message or symptom.

Good problem fields:

Copyproblem: "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:

Copyproblem: "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:

Copycreated: "2026-02-08"

Optional frontmatter fields

These fields add context but are not required for validation.

environment

Technical context for the solution. Recommended.

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

ai_provider

Which AI assistant helped create or verify the solution. Set only if an AI was meaningfully involved.

related

An array of slugs linking to related shares.

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

Copy---
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
• Error message or symptom
• Impact

Solution

Show the fix with complete, runnable code. If there are multiple options, label the recommended one.

Why It Works

Explain the mechanism behind the fix. Do not just restate the solution.

Context

List version requirements first, then add gotchas, alternatives, and related tools.

Section length guidelines