Case Studies skill for Claude Code

A case study persuades when a skeptical reader in the same situation sees a specific problem they recognize, a credible account of what was done, and results with numbers, baselines, and a timeframe that the customer has approved. “Acme transformed its workflow and saw dramatic improvements” persuades no one.

Ground rules

• Evidence first. No draft until you have at least one metric with a baseline and a timeframe, or a concrete qualitative outcome you can state precisely.
• Quotes are real and approved. Never invent or “polish” a quote beyond light cleanup the speaker signs off on.
• Attribute honestly: state what else changed during the period and say “contributed to” when the product was one factor among several.
• The customer is the hero; the product is the tool. Lead with their problem, not your feature list.
• Get written approval from the customer (and legal or PR if either side requires it) before publishing names, logos, numbers, or quotes.

Two kinds

	Customer case study	Engineering case study
Reader	Prospects in a similar role or industry	Engineers facing a similar technical problem
Goal	Show the outcome is achievable for someone like them	Share a transferable approach and its trade-offs
Core evidence	Business metrics, quotes, time to value	Technical metrics, architecture, alternatives considered
Tone	Plain, specific, confident	Candid about dead ends and costs

For narrative engineering posts aimed at the community rather than a structured case, see dev-blog-posts.

Workflow

- [ ] 1. Pick the story and confirm the customer will participate and approve
- [ ] 2. Collect data and run the interview(s)
- [ ] 3. Build the evidence table (metric, before, after, period, source)
- [ ] 4. Find the angle and headline
- [ ] 5. Draft with the standard structure
- [ ] 6. Fact-check every number and quote against sources
- [ ] 7. Customer and legal review; incorporate edits
- [ ] 8. Publish in formats; reuse pieces

1. Pick the story

Good candidates: a customer that matches the target audience, a clear before state, a measurable change, and a champion willing to talk. Confirm early what can be named (company, person, logo, numbers) and whether they need anonymization (“a top-10 US insurer”).

2. Interview

30-45 minutes, recorded with permission, two people if possible (one asks, one notes). Question guide:

1. What does your team do, and what does success look like for you?
2. Before: what were you doing, what was painful, what did it cost (time, money, risk)? Can you put a number on it?
3. What triggered the search for a change? What else did you consider and why not?
4. How did rollout go? What was harder than expected? How long until it was useful?
5. After: what changed, in numbers if possible? What can you do now that you could not?
6. What would you tell a peer considering the same change?
7. Who else should we talk to, and what data can you share?

Ask follow-ups for specifics: “How many hours a week?”, “From what to what?”, “Over what period?”, “How do you measure that?”. The best quotes come from question 6 and from describing the old pain.

For engineering case studies, interview the engineers and pull dashboards, incident records, cost reports, and design docs (see design-docs-rfc) for the facts.

3. Evidence table

Metric	Before	After	Period	Source	Approved
Month-end close time	9 days	3 days	Q1 vs Q3 2026	Customer finance team	Yes
p95 API latency	820 ms	140 ms	30 days pre/post migration	Datadog dashboard	Yes
Infra cost	$48k/mo	$31k/mo	Jan vs Jun 2026	Cloud billing export	Pending

Rules: percentages always with absolute numbers somewhere (“cut close time 67%, from 9 days to 3”); state the period; note confounders (“headcount grew 20% in the same period”). Drop any metric the customer will not approve rather than blurring it.

4. Angle and headline

The angle is the one result most relevant to the target reader. Headline formula: <Customer> <achieved specific result> <by/with how>.

Weak	Strong
Acme Finance Success Story	Acme cut month-end close from 9 days to 3 by automating reconciliation
How Globex Uses Our Platform	Globex moved 2 PB to object storage with zero downtime and 35% lower cost

5. Structure

Customer case study (600-1,200 words):

# <Headline with result>

| Company | <name, industry, size> |
| Challenge | <one line> |
| Solution | <one line> |
| Results | <2-3 metrics with numbers> |

## The challenge
<Their situation and pain, with a number and a quote in their words>

## Why they chose <product>
<Alternatives considered and the deciding factors, briefly>

## The approach
<What was implemented, timeline, who was involved, what was hard>

## The results
<Metrics from the evidence table, each with before/after/period; one quote>

## What's next
<Their next step; signals ongoing relationship>

Engineering case study (1,200-2,500 words): context and constraints (scale, SLOs, team size, deadline) -> the problem with data -> options considered with trade-offs -> what we did, with an architecture diagram -> results with measurements -> what went wrong and what we would do differently -> takeaways a reader can apply.

Writing rules:

• Specific nouns and numbers in every section; cut adjectives that a number could replace.
• Quotes do work the narrative cannot: emotion, credibility, peer advice. One per section at most, attributed with name and title.
• Show the hard part. A rollout with no friction reads as fiction.
• No superlatives (“best-in-class”, “revolutionary”) unless quoting the customer.

6. Fact-check

Re-verify every number against its source row, every quote against the transcript, names and titles against the customer’s current information, and product claims against what the product actually does today. Remove anything that cannot be sourced.

7. Approval

Send the customer a clean draft plus the evidence table, highlighting quotes and numbers needing approval. Expect edits; accept factual corrections, push back gently on removing all specifics (offer ranges or anonymization instead). Keep the written approval with the final version.

8. Formats and reuse

From one approved study: web page, PDF one-pager (snapshot box + results + one quote), sales slide, social posts (one metric and one quote each; see social-media-posts), and a short quote bank for landing pages (see landing-page-copy). Reuse only the approved wording.

Gotchas

• Reporting the best week instead of a sustained period gets called out by informed readers and embarrasses the customer.
• “Up to 10x faster” claims without context invite disbelief; say what was measured.
• Interviewing only the buyer misses the hands-on story; talk to a user too.
• Customer approvals can take weeks; start the request at the interview stage.
• Anonymized case studies still need enough detail (industry, size, scale) to be credible.

Output contract

**Headline:** <customer + result + how>
**Snapshot:** company, challenge, solution, 2-3 results
**Evidence table:** metric, before, after, period, source, approval status
**Body:** challenge -> why chosen -> approach -> results -> what's next
  (or engineering: context -> problem -> options -> solution -> results -> lessons)
**Quotes:** <n>, each approved, attributed (name, title)
**Approvals:** customer <date>, legal/PR <date or n/a>