developer-case-study

Developer Case Study

You are writing someone else's engineering story. A developer case study says: these engineers ran this technology in production, here is what changed, here is what it cost them. The reader is an engineer deciding whether the same move works in their own system - not a buyer looking for reassurance.

That reader discounts an all-upside narrative on sight. Your leverage is evidence discipline and honesty about the parts that hurt, not prose polish.

Scope check

Confirm the artefact before starting. Route elsewhere when:

• The system is your own and no external adopter is involved → engineering blog post skill.
• The story is your own project's progress, shared as it happens → build-in-public skill.
• The reader needs to learn or install something → tutorial or quickstart skill.
• The material is "what shipped in v2.4" or "how to move from v1 to v2" → changelog or migration-guide skill.
• The user wants a portfolio piece about work they did → that is a personal case study, and its hero is the author. Say so; this skill inverts that framing.

See the References section for the exact identifiers.

Interview

Ask the case-study owner these before touching the story, one question at a time, multiple-choice where you can. Stop as soon as you can judge whether the story is publishable.

Memory: Store a few info about the current task or project context. When memory lives in a file, use devrel-context.md; if a different memory system is in use, rely on that instead. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.

1. Who is the adopter, and is this in production today or still an evaluation?
2. Who will you interview, and what is their hands-on role? Can you also get their manager or the platform owner?
3. What evidence already exists on your side - support threads, migration issues or PRs, usage telemetry, account notes, their own blog posts or talks?
4. What changed, in numbers, and who inside their team can vouch for those numbers?
5. Who grants permission to name the company, the person, and to use the logo - and how long does each take?
6. Is there a security or legal review on their side, and has anyone engaged it yet?
7. Where does this publish, and does it need a sales one-pager version too?
8. What is the one sentence a reader should repeat to a colleague afterwards?
9. By what date must this be live, and what happens on that date? A date inside the month deletes any enterprise candidate whose legal review alone runs longer, and promotes the adopter who can approve in a message.
10. One-off win - a study for one stalled deal - or a story bank you keep filling? A one-off promotes whichever candidate is closest to approval; a bank promotes the empty row in the coverage table, even when that row is the slowest story to land.
11. What is the effort ceiling, counting the customer's time and goodwill as well as yours? One interview and one review round rules out multi-stakeholder enterprise stories; an account team willing to spend a quarter of relationship capital opens them.

If your harness has persistent memory, store the answers to 5, 6 and 7. Those are per-customer and per-program conventions that stay true across every story you write with them.

Workflow

1. Qualify the story against the gates below, and where several adopters are candidates, rank them with "Which story to chase first" before spending an hour on any of them. Kill or downgrade here - a story that fails the gates cannot be rescued in editing.
2. Reconstruct it from your own evidence first. Read the tickets, issues, PRs and telemetry before the call, so you arrive with specifics to confirm rather than open prompts to fill.
3. Open the approval track in parallel. Read the contract's publicity clause, then ask who grants quotes, metrics and security clearance before drafting - their answer decides which version of the story is writable.
4. Run the source interview. Follow ./references/source-interview-guide.md. Record with consent, keep the transcript.
5. Build the evidence ledger. One row per claim the study will make: the claim, its evidence class, the instrument behind it, who can re-derive it. Do this before drafting.
6. Confirm the spine and the headline number with the owner. Cheap to change now, expensive after 1,200 words.
7. Draft against the spine in ./references/case-study-outline.md, quotes verbatim from the transcript.
8. Write the limitations section from the interview's cost and unsolved-work answers. Never skip it - see below.
9. Run the humanizer pass, then the publication gate. Iterate until every check passes.
10. Send for approval with a marked decision list and a dated deadline, per ./references/approval-and-anonymization.md. Apply their edits, then package the derivative versions.

Invocation examples

• "We just finished migrating Northwind's billing pipeline onto our workflow engine. Write the case study." → run the whole workflow from step 1.
• "Here's the transcript of my call with their staff engineer plus a metrics screenshot. Draft it." → skip to step 5; build the evidence ledger from the transcript, flag every claim the transcript cannot support.
• "Legal came back and killed the company name. What now?" → jump to the anonymization ladder, propose the next rung down, and name what it costs.
• "Is this story even worth writing?" → run the qualification gates only, and answer with a verdict plus the missing gate.
• "We have four customers who said yes, which do we do?" → the ranking in "Which story to chase first", applied to the four by name, with the ones their constraints delete removed rather than ordered last.
• "Turn the approved Northwind study into a one-pager for sales." → derivative versions only; confirm the existing approval covers the new surface first.

Unless the user asks for something else, deliver six parts in this order:

1. Verdict line - publishable, publishable as X, or not yet, with the reason.
2. Evidence ledger - one row per claim: claim, class, instrument, window, who can re-derive it.
3. The draft - the eight-section spine, quotes verbatim, limitations included.
4. Approval package - the decisions to confirm, marked, with a suggested deadline and default.
5. Gate report - the seven checks, each pass/fail, with the fix applied.
6. Derivatives - the one-pager or other requested versions, only after approval.

Produce the verdict and the ledger before any drafting. A ledger built after the prose is a ledger written to justify it.

Story qualification gates

Five gates - this skill's own checklist, not a published standard. A publishable story clears all five:

• Production, not pilot. Real traffic, real consequences. An evaluation is a testimonial at best.
• A measured before-state. No baseline means no honest delta, only vibes.
• A named human who will talk. Nobody to quote means nobody to believe.
• A decision a reader can reuse. Alternatives were considered and one won for a stated reason.
• A plausible path to approval. Someone can actually authorise the company name or a workable anonymised version.

Failing one gate does not always mean no story:

• Missing production: wait.
• Missing baseline: publish a scale/architecture story without a delta claim.
• Missing approval: descend the anonymization ladder.
• Missing a human: it is an engineering pattern post, not a case study. Say that out loud rather than dressing it up.

Which story to chase first

When several adopters could carry a study, the choice is not which one is most impressive - it is which one returns the most published proof per hour spent, counting the customer's own time and goodwill as the scarcest input. Adopter type predicts both sides of that ratio, so rank candidates by it and chase in this order.

• efficiency (published proof per hour of chasing - the default order): startup or scale-up > individual developer or OSS maintainer > consumer-product engineering team > enterprise
• effort (heaviest first, customer time and goodwill included): enterprise > consumer-product engineering team > startup or scale-up > individual developer
• value (strongest proof to an undecided reader): enterprise > consumer-product engineering team > startup or scale-up > individual developer
• compliance cost (heaviest review first): enterprise > consumer-product engineering team > startup or scale-up > individual developer

The value line assumes the reader is evaluating for a team inside a company. It inverts when the product's own adopters are solo developers and maintainers - then the indie story is the strongest proof available and the enterprise one reads as irrelevant. Re-rank against who actually buys before using the default.

In efficiency order, with what each type costs and buys, and the craft difference each forces:

1. Startup or scale-up B2B adopter - approval is one or two people and a week. The best ratio on the list, and the risk is the mirror of the enterprise one: nobody checks the numbers. Verify them yourself before publishing, and re-verify before reusing - small companies pivot and migrate away.
2. Individual developer, indie hacker or OSS maintainer - near-zero approval cost; consent is a message and the person is the brand. Metrics are personal-scale (build minutes, a hosting bill, a weekend of work) and perfectly credible at that scale - never inflate them into enterprise language. Ask explicitly whether they want their employer mentioned.
3. Consumer-product engineering team (B2C product, developer story) - a communications function exists but the story does not touch their own users, so review is narrower than an enterprise's. The adopter's users never read this; the audience is peer engineers. Push harder on architecture and scale mechanics and drop the buyer-facing business framing entirely.
4. Enterprise B2B adopter - a quarter, with weeks of review, a communications team that owns the narrative, heavy redaction of absolute numbers, and a second round after security. Engage legal before drafting. Their engineers will read it, so accuracy failures come back through the account team.

What this order starves is the named enterprise production reference: the strongest proof available to a reader who has to justify the choice internally, and the most expensive story on the list in both legal review and customer goodwill. An efficiency ranking demotes it every quarter, and the story bank fills with small stories that never move an enterprise evaluation. Promote it above everything when a live deal is stalled for want of a peer reference at that size, or when the coverage table's enterprise row is empty - that gap has no cheap substitute, and three startup studies do not add up to one.

Delete rather than demote. A customer whose legal team will not approve a public reference is removed from the candidate list, not parked at the bottom. Keep them only if a rung of the anonymization ladder still clears the qualification gates.

Otherwise, the candidate is gone: a "maybe next quarter" name keeps consuming account-team asks and the relationship capital that goes with them. A candidate still in evaluation rather than production is deleted the same way, since it fails the first gate and waiting for it is not a plan.

This order is a default, not a law: it shifts with context and with who chases the story.

• An account team that already has a warm relationship with one enterprise has paid most of that story's cost already.
• A maintainer who has publicly written about the product is halfway to a published study before anyone calls.

Number discipline

Every number carries four attributes or it does not ship:

• Value before.
• Value after.
• The instrument that produced it.
• The measurement window.

Evidence class	What you have	How to write it
Measured	Both sides from the same instrument	State it directly, with the instrument and window
Partially measured	After-value instrumented, before-value estimated	State it, and mark the estimate as an estimate
Reported	The customer's number, uninstrumented	Attribute it: "the team estimates…"
Directional	Only a qualitative claim survived	Drop the number; use the engineer's own words

Two well-sourced numbers beat six loose ones. Ratios travel better than absolutes when the customer will not clear absolutes ("cut infra cost by a third"), and cycle-time and reliability figures travel better than raw volume, because a reader can compare them to their own system without knowing the customer's scale.

Don't:

• Compute a number the customer did not confirm.
• Annualize a one-month result.
• Attribute a business outcome to your product when the customer changed three things at once. Say what else changed.

Hold this skill's own numbers to the same rule. ./references/evidence-and-sources.md splits every threshold in this file into sourced or self-set. Quote a self-set baseline only as a working baseline - never to an adopter as an industry standard.

The spine

Published studies converge on Challenge / Solution / Results: four independent instances carry the same three beats - two vendor studies and two generic marketing-skill templates (sources in ./references/evidence-and-sources.md). Keep them, and add the three those templates leave out: alternatives rejected, metric provenance, limitations.

The word budgets below are self-set proportions for a 1,200-1,800-word target - itself self-set, chosen to sit just under the three measured vendor studies (~1,650, ~2,100 and ~2,400 words, none with a dedicated limitations section). Scale them to the material.

1. Headline outcome - the number and the shape of the change (~60 words)
2. The adopter and the system in question (~120)
3. The before-state and what it cost them (~250)
4. Why this technology - alternatives weighed and rejected (~200)
5. What they built - architecture, named components, sequencing (~400)
6. Results - the numbers, with method (~200)
7. What it cost and what is still unsolved (~200)
8. What is next (~70)

Sections 4, 5 and 7 are what separate this from a testimonial. If the material only fills 1, 2, 6 and 8, you have a quote card - publish it as one.

Read [./references/case-study-outline.md](./references/case-study-

...