Examples
Annotated good and bad SHARE.md examples showing what makes a share effective and common mistakes to avoid.
Annotated examples of good and bad shares. Use them to calibrate quality.
Good example: fix type
A well-structured fix for Prisma N+1 queries.
Frontmatter
---
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
---Good because: Title verb matches solution_type. Problem field includes the observable symptom for search. Tags cover technology, domain, and descriptor.
Problem section
## Problem
Loading a list of records and then accessing their relations triggers one
additional query per record:
```typescript
const posts = await prisma.post.findMany();
for (const post of posts) {
const author = await prisma.user.findUnique({
where: { id: post.authorId },
});
}With 100 posts, this generates 101 database queries.
Good because: Minimal reproduction, quantified impact, no fix leakage.
Solution section
## Solution
**Option 1: Use `include` to eager-load relations (recommended)**
```typescript
const posts = await prisma.post.findMany({
include: { author: true },
});Option 2: Use select for specific fields
const posts = await prisma.post.findMany({
select: {
id: true,
title: true,
author: { select: { name: true, email: true } },
},
});Option 3: Use relationLoadStrategy: "join" (Prisma 5.9+)
const posts = await prisma.post.findMany({
relationLoadStrategy: "join",
include: { author: true },
});
<Callout type="info">
**Good because:** Labeled options, recommended default, version noted in the label, complete code with language labels.
</Callout>
### Why It Works section
The share explains that Prisma does not load relations by default, that the N+1 arises from manual looping, and that `include` changes the behavior to a single query with joined relation loading.
<Callout type="info">
**Good because:** Explains root cause, not just "add include." Written as prose.
</Callout>
### Context section
```markdown
## Context
- Prisma 4.x+ for `include`, Prisma 5.9+ for `relationLoadStrategy: "join"`
- Use Prisma's query logging to detect N+1: `new PrismaClient({ log: ["query"] })`
- For GraphQL resolvers, consider DataLoader patterns
- `select` is more efficient than `include` when you don't need all columns
Good because: Version requirements first. Includes debugging tip and related patterns.
Good example: pattern type
---
title: "Use TypeScript satisfies operator for type-safe config objects"
slug: fix-typescript-satisfies-type-safety
tags: [typescript, satisfies, type-safety, config]
problem: "Type annotation on config object widens types and loses literal inference"
solution_type: pattern
created: "2026-02-08"
environment:
language: typescript
version: "4.9+"
---Good because: Title verb "Use" matches solution_type: pattern. Problem describes the technical symptom.
The body follows the same structure: Problem shows type widening with a concrete Routes type, Solution demonstrates satisfies, and Why It Works explains why literal inference is preserved.
Common mistakes
Bad frontmatter
---
title: "fix stuff"
slug: Fix_Stuff
tags: [Fix, stuff, things, misc, general, code, programming, software, development, engineering, TypeScript]
problem: "broken"
solution_type: pattern
created: Feb 8
---Problems: Vague title. Slug has uppercase and underscores. Tags include uppercase and exceed 10 items. Problem has no symptom. Wrong date format.
Bad Problem section
## Problem
This is a common issue that many developers face when working with modern web frameworks. There are several approaches to solving it, and in this share I will walk you through the best one I found after trying many different things.Problems: No code, no error message, no impact. Reads like a blog post.
Bad Solution section
## Solution
Just add `include` to your query. This should fix it.
```
prisma.post.findMany({ include: { author: true } })
```Problems: No language label. Incomplete snippet. Explanation mixed into text instead of code comments.
Bad Why It Works section
## Why It Works
It works because we added `include: { author: true }` to the query. This tells Prisma to include the author in the results.Problems: Restates the solution instead of explaining the mechanism.
Bad Context section
## Context
This solution uses Prisma's include feature to eager-load relations. When you use include, Prisma will automatically join the related table in the SQL query. This is much more efficient than loading each relation individually.Problems: Paragraph instead of bullets. Repeats the solution explanation. No version numbers, no gotchas, no related tools.
Quality checklist
Run through this before publishing. Machine-checkable rules are caught by npx shareful-ai check.
Frontmatter:
- Title names the technology and problem, verb matches
solution_type - Problem field includes the error message or observable symptom
solution_typematches the content, not just the title
Problem section:
- Shows broken code with a minimal reproduction
- Includes exact error message or quantified impact
- Does not explain the fix
Solution section:
- All code blocks have language labels
- Code is complete and runnable, not fragments
- Multiple options labeled with "(recommended)" on the default
Why It Works section:
- Explains the root cause, not just restates the fix
- Written as prose
Context section:
- Formatted as a bulleted list
- Version requirements listed first
- Includes at least one gotcha or limitation
Next steps
- Share format specification - field constraints and validation rules
- Creating shares - writing tips