> ## Documentation Index
> Fetch the complete documentation index at: https://shareful.blode.md/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`

| Constraint | Value |
| --- | --- |
| Type | string |
| Max length | 128 characters |
| Required | Yes |

Start with a verb that matches the `solution_type`:

| solution_type | Verb convention | Example |
| --- | --- | --- |
| `fix` | "Fix ..." | "Fix Prisma N+1 query problem with includes and joins" |
| `workaround` | "Workaround for ..." | "Workaround for Next.js 14 middleware redirect loop" |
| `pattern` | "Use ...", "Implement ..." | "Use TypeScript satisfies operator for type-safe config objects" |
| `reference` | "Guide to ...", "Reference for ..." | "Guide to PostgreSQL JSONB query operators" |
| `config` | "Configure ..." | "Configure ESLint flat config for TypeScript monorepos" |

Good titles:

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

Bad titles:

```yaml
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.

| Constraint | Value |
| --- | --- |
| Type | string |
| Max length | 64 characters |
| Pattern | `/^[a-z0-9-]+$/` |
| Required | Yes |

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:

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

Bad slugs:

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

### `tags`

| Constraint | Value |
| --- | --- |
| Type | string[] |
| Min items | 1 |
| Max items | 10 |
| Each max length | 32 characters |
| Case | Lowercase only |
| Required | Yes |

Cover three categories:

1. Primary technology
2. Problem domain
3. Descriptors

Good tags:

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

Bad tags:

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

### `problem`

| Constraint | Value |
| --- | --- |
| Type | string |
| Max length | 256 characters |
| Required | Yes |

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

Good problem fields:

```yaml
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:

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

### `solution_type`

| Constraint | Value |
| --- | --- |
| Type | enum |
| Values | `fix`, `workaround`, `pattern`, `reference`, `config` |
| Required | Yes |

| Value | Description | When to use |
| --- | --- | --- |
| `fix` | A direct fix for a bug or error | The solution permanently resolves the root cause |
| `workaround` | A temporary workaround for a known issue | The root cause is upstream or unfixable; this bypasses it |
| `pattern` | A reusable coding pattern or architecture | The solution generalizes beyond a single error |
| `reference` | A lookup guide or cheat sheet | The content is informational, not fixing a specific error |
| `config` | A configuration change resolving a setup issue | The fix is entirely in config files, not application code |

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

### `created`

| Constraint | Value |
| --- | --- |
| Type | string |
| Format | `YYYY-MM-DD` |
| Required | Yes |

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

```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.

```yaml
environment:
  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

```yaml
---
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