samber/developer-relations-skills已通过检查
SKILL DETAIL
developer-case-study
samber/developer-relations-skills/developer-case-study
Turns a customer's real production deployment into a technical case study engineers believe - measured numbers tied to how they were measured, before-and-after architecture, published limitations, and cleared naming and quote approval. Use whenever the user mentions a customer case study, a technical case study, a developer adoption or success story, a reference customer, or wants to turn a user interview, migration or production rollout into published proof - even if they only say "a post about how Acme uses us". Do NOT use for a post about your own system - use samber/developer-relations-skills@engineering-blog-post; for your own project's ongoing progress use samber/developer-relations-skills@build-in-public.
安装量 · 417查看来源
Installation
npx skills add https://github.com/samber/developer-relations-skills --skill developer-case-study
技能文件
SKILL.md
最近同步 · 2026年10月23日
evals/evals.json›
{
"skill_name": "developer-case-study",
"evals": [
{
"id": 1,
"prompt": "We wrapped the Kestrel Freight rollout last month. They moved their dispatch pipeline off cron onto our workflow engine and it has been live in production for nine weeks now. I have the recording of my call with Dana Okafor (Staff Engineer, Dispatch), our own usage telemetry, and a screenshot of their Grafana board. Their p95 dispatch latency went from 8.4 minutes to 95 seconds on that board, measured over the four weeks either side of cutover. Dana also reckons on-call load dropped by about half, though nobody tracked that anywhere. Write the case study, we want it on the blog this month.",
"expected_output": "A publishable verdict and a per-claim evidence ledger produced before any prose, then a draft on the eight-section spine with each figure classified by evidence class and the on-call claim attributed rather than stated as measured.",
"files": [],
"expectations": [
"Produces a verdict line stating whether the story is publishable, and in what form, before any draft prose appears.",
"Produces the evidence ledger before the draft, not after it.",
"The ledger carries one row per claim the study will make.",
"Each ledger row states the claim, its evidence class, the instrument behind it, the measurement window, and who can re-derive it.",
"Classifies the p95 dispatch latency change (8.4 minutes to 95 seconds) as measured, naming the Grafana board as the instrument and the four weeks either side of cutover as the window.",
"Classifies the halved on-call load as reported rather than measured, and attributes it to the team (for example 'the team estimates') instead of stating it flatly.",
"Delivers the parts in the order verdict, evidence ledger, draft, approval package, gate report, derivatives.",
"Does not treat the approval package as optional or as something handled after publication.",
"The draft spine includes a section on alternatives weighed and rejected, a results section carrying measurement method, and a limitations section, rather than only challenge, solution and results.",
"Flags that no alternatives-considered material exists in the supplied evidence and names it as something to go back to Dana for, rather than inventing rejected options.",
"Uses quotes only as verbatim material attributable to the recording, and invents no quote."
]
},
{
"id": 2,
"prompt": "Bit stuck on this one. Helio Diagnostics has been running our ingest SDK in production for five months on real patient-scheduling traffic, and their lead engineer Marcus Vance is happy to be quoted and named. Problem: when I asked what the old system's throughput and error rate were, he said they never really measured it, there were no dashboards on the legacy path at all. Their current numbers look strong though, 2.1M events a day and 99.97% delivery according to our telemetry. Can we still get a case study out of this, and what should it say?",
"expected_output": "A verdict that the missing measured before-state is the only failing gate, with a recommendation to publish a scale and architecture story carrying no delta claim, plus a flag that the delivery figure is vendor-side and needs customer confirmation.",
"files": [],
"expectations": [
"Names the missing measured before-state as the qualification gate this story fails.",
"States that the other gates (production not pilot, a named human who will talk, a decision a reader can reuse, a plausible path to approval) are satisfied, rather than treating the story as dead.",
"Recommends publishing a scale or architecture story without a delta claim, rather than waiting for a baseline or killing the story.",
"Explicitly forbids constructing a before-and-after improvement figure out of the current numbers.",
"Does not reconstruct, estimate or infer the legacy throughput or error rate.",
"Notes the 99.97% delivery figure comes from vendor-side telemetry and needs someone at Helio to confirm and vouch for it.",
"Warns that every number coming from your own dashboards with nothing the customer can confirm is a disqualifying signal.",
"Keeps the architecture and rejected-alternatives sections load-bearing, since the results section cannot carry a delta.",
"Does not fall back to a testimonial or quote card, given that a named human and a production deployment both exist.",
"Names identifying who on Helio's side can confirm the published numbers as part of the plan."
]
},
{
"id": 3,
"prompt": "Our standard terms carry this clause: 'Customer grants Vendor a non-exclusive, royalty-free licence to use and reproduce Customer's trademarks, trade names and logos in Vendor's marketing materials and to indicate that Customer is a customer.' Coastline Rail signed it. So I am clear to publish the study with their name, their staff engineer's quotes, the throughput numbers and the architecture diagram without going round asking people individually, right? The deal is closing this quarter and I do not want to spook anyone with a big legal ask.",
"expected_output": "A correction that the clause licenses name, logo and the fact of being a customer only, plus the four remaining permissions and their usual holders, and a warning about the relationship cost of publishing on the strength of a logo clause.",
"files": [],
"expectations": [
"Confirms the clause does cover the company name, the logo, and the public statement that Coastline Rail is a customer.",
"States the clause does not cover quotes.",
"States the clause does not cover metrics.",
"States the clause does not cover the architecture description.",
"States the clause does not cover a narrative about how the customer runs their systems.",
"Names four separate permissions still required: the engineer's consent to be quoted, their manager's consent to spend team credibility, communications sign-off on company name and published wording, and security or legal review of the technical detail.",
"Notes those permissions are often held by four different people and that you ask who holds each at first contact.",
"Warns that publishing quotes or metrics on the strength of a logo clause is how a reference relationship ends.",
"Does not advise publishing first and correcting later, and does not treat silence or the signed contract as consent for the quotes and metrics.",
"Notes that if the full story is refused, the clause still leaves a lighter artefact available, such as the logo wall or the fact of being a customer."
]
},
{
"id": 4,
"prompt": "Bad news on the Vantage Payments study. Their comms team will not let us use the company name, full stop, they never appear in vendor marketing. Their staff engineer Ines Duarte is personally fine being named and quoted, and their security team already cleared the metrics and the architecture section. The draft is finished. What is the move? I was going to just strip the company name and call them 'a large European payments company', keep Ines's name on the quotes, and ship it.",
"expected_output": "A descent to the rung where the company is unnamed but carries an identifying descriptor, with the engineer attributed by role rather than name, the credibility cost named, and the proposed descriptor checked for re-identification risk.",
"files": [],
"expectations": [
"Identifies the top two rungs (named company with named engineer, and named company with unnamed engineer) as both unavailable, since each names the company.",
"Recommends the rung of an unnamed company carrying an identifying descriptor, with the metrics left intact.",
"Addresses that keeping Ines Duarte's name on the quotes re-identifies her employer, and attributes the quote by role and team instead.",
"Names the credibility cost of the descent rather than presenting the lower rung as an equivalent or neutral option.",
"Instructs descending one rung at a time rather than dropping straight to a category descriptor or a pattern write-up.",
"Warns against sharpening the descriptor until the company becomes identifiable while the study still claims anonymity.",
"Assesses the proposed descriptor 'a large European payments company' against re-identification risk rather than accepting it unexamined.",
"Does not present the rungs as a menu to pick from by effort, cost or convenience.",
"States that at this rung the numbers now carry the whole study.",
"Confirms whether the story still clears the qualification gates at that rung, or names which gate it would fail.",
"Notes that the bottom rung, a composite or pattern write-up with no attributed quote, is no longer a case study and must be published and labelled as an engineering-pattern post."
]
},
{
"id": 5,
"prompt": "Draft is with me for the Meridian Health study. Their engineering manager sent back what he wants in the challenges section, verbatim: (1) 'We plan to consolidate our two orchestration languages next year.' (2) 'Chat-based approvals are on our roadmap for Q3.' (3) 'We would like to extend this to the claims pipeline eventually.' He says that is their honest account of what is left. Slot those in and let us ship, the approvals are all signed and the alternatives section is already in, we are just waiting on this bit.",
"expected_output": "A refusal to publish the three roadmap items as limitations, the rule that separates a cost from a plan, a concrete list of replacement questions to put back to Meridian, and a conversion of at least one item into the cost a reader would inherit.",
"files": [],
"expectations": [
"Identifies all three supplied items as roadmap statements rather than limitations.",
"States the distinguishing rule: a limitation is a cost the reader would inherit, not a plan.",
"Refuses to publish the section as supplied, or marks the limitations check as failing.",
"Asks Meridian for the migration effort in engineer-weeks.",
"Asks about the dual-running period.",
"Asks what broke during rollout.",
"Asks what the team had to retrain on.",
"Asks which workloads they deliberately did not move.",
"Asks what still does not work.",
"Requires the section to state who should not copy this architecture.",
"Converts item (1) from a plan into a present cost, for example that the orchestration layer sits in a different language from the rest of the team's work so every change routes through the few people who know both, rather than simply deleting the item.",
"Notes that if the customer strikes the limitations section entirely the study is weaker but still shippable, while striking limitations and alternatives together makes it an advertisement that must be framed as one to the owner."
]
},
{
"id": 6,
"prompt": "Four adopters said yes this month and I have bandwidth for maybe two studies this quarter. (a) Brightloom, a 40-person B2B startup, their CTO approves everything himself, live for four months. (b) Tobias Reiner, solo maintainer of a popular Rust crate, already blogged about using us last spring. (c) Kaleido, a consumer photo app with a 30-engineer platform team, in production eight months. (d) Anvil Group, a 14,000-employee insurer whose legal takes about a quarter and who have never approved a vendor case study, though our biggest open deal, Continental Mutual at a similar size, has been stalled two months because their architecture board wants to talk to a peer at their scale. Also (e) Padma at Lockstep is keen but they are still in evaluation, not production. Rank them for me.",
"expected_output": "A stated default efficiency ranking, Lockstep deleted for failing the production gate, Anvil deleted or kept only via an anonymization rung, and the stalled peer-reference deal named as the condition that promotes an enterprise story above the default.",
"files": [],
"expectations": [
"States the default ranking axis as published proof per hour of chasing, and gives the order startup or scale-up, then individual developer or OSS maintainer, then consumer-product engineering team, then enterprise.",
"Says the ranking out loud rather than leaving it implied by the order of the list.",
"Deletes Lockstep from the candidate list rather than ranking it last, because a deployment still in evaluation fails the production gate.",
"Names the stalled Continental Mutual deal as the condition that promotes an enterprise story above the default efficiency order.",
"States that three startup studies do not add up to one enterprise reference at that size.",
"Treats Anvil Group's never-approved posture as grounds for deletion from the candidate list unless a rung of the anonymization ladder still clears the qualification gates, rather than parking them at the bottom.",
"Notes that an anonymised Anvil study loses the named-peer property the stalled deal actually needs, rather than treating anonymisation as a free substitute.",
"Notes that Tobias Reiner having already blogged about the product means most of that story's cost is already paid.",
"Warns against inflating a solo maintainer's personal-scale figures (build minutes, a hosting bill, a weekend of work) into enterprise language.",
"For Kaleido, pushes harder on architecture and scale mechanics and drops buyer-facing business framing, since the audience is peer engineers and the adopter's own users never read it.",
"Warns that Brightloom's numbers need verifying yourself, because at that size nobody else checks them.",
"States the ranking is a default that shifts with context and with who chases the story, not a law."
]
},
{
"id": 7,
"prompt": "Pulling the results section together for the Orbit Cargo study. What I have: their build queue wait went from a 22 minute median to a 6 minute median, both figures off their Buildkite dashboard, the before value over the six weeks prior and the after value over the three weeks post-cutover. They also cut their monthly CI bill from $18,400 to $9,900 in the first month after the move. Their VP said support tickets are way down but nothing tracked that. In the same month they also moved their runner fleet to Graviton and deleted two flaky test suites. Marketing wants the headline to read '$102,000 saved annually' and 'over 70% faster builds'. Draft the results section.",
"expected_output": "A results section refusing the annualised figure and the unconfirmed derived percentage, naming the two other changes in the same window, classifying each claim, and expressing the infrastructure cost as a ratio rather than absolute dollars.",
"files": [],
"expectations": [
"Refuses the '$102,000 saved annually' headline because annualising a one-month result is not permitted.",
"Names the Graviton runner migration and the two deleted flaky test suites as other changes inside the same window, and states them in the study rather than crediting the product alone for the improvement.",
"Classifies the build queue figures as measured, naming the Buildkite dashboard as the instrument and the six weeks before and three weeks after as the windows.",
"Treats the untracked support-ticket claim as directional: drops any number and uses the speaker's own words.",
"Flags 'over 70% faster builds' as a figure computed rather than confirmed by the customer, and requires it be put back to them before it ships.",
"Expresses the CI bill change as a ratio, for example cutting CI spend by roughly half, instead of publishing the absolute dollar figures, noting absolute infrastructure costs are predictably struck in review.",
"Places each number's instrument and window next to the number rather than in a footnote.",
"Keeps the results section to between two and four numbers rather than publishing every figure available.",
"States that two well-sourced numbers beat six loose ones.",
"Notes cycle-time figures travel further to a reader than raw volume or absolute spend, because they can be compared without knowing the customer's scale.",
"Every published number carries a value before, a value after, the instrument that produced it, and the measurement window."
]
},
{
"id": 8,
"prompt": "Set me up for the Fairhaven Robotics call. I have a 45 minute Zoom booked with their VP Engineering, and the two backend engineers who did the actual work are joining the same call. Plan is to ask how the migration went overall, whether they are happy with the performance now, and whether they would recommend us to a peer. Then I will write it up from my notes afterwards. What questions should I ask?",
"expected_output": "A restructured interview: the implementing engineers booked separately and longer than the VP, a recorded call with consent captured on the recording, and a ladder of questions about specifics that already happened rather than opinions.",
"files": [],
"expectations": [
"Recommends splitting the call: the implementing engineers for about an hour, the VP separately for about twenty minutes.",
"Gives the reason for the split: in a joint call the hands-on voice defers, and the hands-on voice is the one readers trust.",
"Rejects writing up from notes and requires a recording, with consent asked at the start of the call and confirmed on the recording itself.",
"States the transcript is kept until publication alongside the approval file, because verbatim quotes are the backbone and paraphrase drifts into vendor register.",
"Rewrites 'are you happy with the performance' into a question about what a named dashboard read before cutover and what it reads now.",
"Rejects 'would you recommend us to a peer' as an opinion or hypothetical question that invites a compliment rather than producing a publishable fact.",
"Names the questioning rule being applied: ask about specifics that already happened, never about opinions or hypotheticals.",
"Instructs sending an agenda beforehand asking them to bring the before and after dashboard numbers, because an engineer who has not looked at the old dashboard cannot produce a baseline from memory.",
"Orders the questions as a ladder where each rung needs the previous one concrete, covering system context, before-state, cost of the before-state, trigger, alternatives, implementation, numbers, what it cost, what is still unsolved, and advice to a peer.",
"Includes an alternatives rung that asks what each rejected option did better, not only why each was rejected.",
"Includes a rung covering what they deliberately did not move, what still does not work, and who should not copy this setup.",
"Notes the publishable quote usually appears at the advice-to-a-peer rung, when the engineer stops reporting and starts explaining.",
"Instructs reading numbers back with their instrument and confirming them on the recording, and confirming name spelling and exact job title during the call."
]
},
{
"id": 9,
"prompt": "Here is my near-final draft of the Stonebridge Bank study, tell me if it is ready to go. 'Stonebridge's migration to our platform was seamless. The team saw game-changing improvements in deployment frequency and now enjoys effortless rollbacks. As their Director of Platform Engineering put it, the solution has been a transformative addition to their toolchain, enabling them to deliver value to customers faster than ever before. Deployments rose sharply and incidents fell. The team plans further adoption across the org.' For context, their director actually said on the call: 'We went from deploying Tuesdays only to about nine times a week, and I stopped getting the Friday rollback ping.' I tightened it up for our blog voice. The numbers are in our internal deck. Clean up the prose and ship it.",
"expected_output": "A per-check gate report failing on superlatives, quote fidelity, claim classification, instrument and window, limitations, alternatives and approval evidence, with the verbatim quote restored and the humanizer pass placed before the gate.",
"files": [],
"expectations": [
"Reports each of the seven publication-gate checks individually as pass or fail, rather than returning a single overall verdict.",
"Fails the unsupported-superlatives check and removes or backs with a number every instance of 'seamless', 'game-changing', 'effortless', 'transformative' and 'faster than ever before'.",
"Fails the quote check and restores the director's verbatim sentence about deploying Tuesdays only, about nine times a week, and the Friday rollback ping.",
"States that the tightened-for-blog-voice version is not a quote and must not be published as one.",
"Fails the claim-classification check, because 'deployments rose sharply and incidents fell' carries no evidence class.",
"Fails the instrument-and-window check, stating that 'in our internal deck' does not satisfy it and each number needs its instrument and window stated or one click away.",
"Fails the limitations check: no limitation is published that is specific enough for a reader to decide against you on it.",
"Fails the alternatives check: no rejected alternative is named.",
"Fails the approval-evidence check: nothing is on file for company name, logo, quotes or security review.",
"Requires the director's confirmed exact name and title for attribution rather than the bare role.",
"Places the humanizer pass before the publication gate rather than in place of it.",
"States the humanizer pass must preserve every quote, every number, version strings, component names and the architecture description exactly as written, because a humanised quote is a fabricated quote.",
"Requires two human reads before publishing: the interviewed engineer confirming technical accuracy, and someone outside the account checking it is comprehensible without insider vocabulary."
]
},
{
"id": 10,
"prompt": "The Larkspur study went live yesterday, approval all signed for the blog post. We are a pure open-source project, no sales team and no deals. We make money from hosted support plans people sign up for on the site with a credit card. I want to get everything I can out of this: a one-page PDF, a conference talk, a post from their engineer on their own blog, and a link from the docs. What order do I do them in, and how long should each take?",
"expected_output": "A ranking by reuse per hour that puts the documentation cross-link first, skips the sales one-pager entirely because no sales motion exists, and flags that the signed approval does not yet cover any of the new surfaces.",
"files": [],
"expectations": [
"Ranks the derivative versions by reuse per hour and states the ranking out loud.",
"Puts the documentation cross-link first, at near-zero effort, sitting where an evaluator already reads.",
"Skips the sales one-pager rather than ranking it, because there is no sales motion at this company.",
"States that the one-pager is the highest value of the set wherever a sales motion exists at all, and worthless where none does.",
"Gives orders of magnitude rather than precise estimates: near-zero for the docs link, about an hour for the community post, about a day for conference material.",
"Notes the engineer's own post under their own name travels further than anything published under yours.",
"Notes only that engineer can authorise the community post.",
"Notes conference material depends on a slot existing and pays nothing until the talk is accepted, while the before-and-after architecture is already a slide so the marginal cost is low.",
"Checks whether the existing approval covers each new surface and flags that it does not, since permission was signed for the blog post only.",
"Advises asking for the derivative permissions while the reviewer is still engaged, ideally before approval rather than after.",
"Recommends filing the study's atoms, each metric, each quote and the architecture diagram, into a proof library with a public or private flag.",
"Gives the reason for the proof library: nobody re-reads a full-length study to find one number."
]
},
{
"id": 11,
"prompt": "I want a case study on how we rebuilt our own ingestion layer from Kafka to Redpanda last spring. Big architectural change, 40% cost drop, and our staff engineer Rui will give quotes. Give it the same treatment you would give a customer story. Separately, my teammate wants one about the migration project she led here, for her promo packet, so maybe do both in the same format.",
"expected_output": "A scope check that routes the internal rebuild to the engineering blog post skill and identifies the promo-packet piece as a personal case study whose hero is the author, declining to apply the customer case study spine to either.",
"files": [],
"expectations": [
"Declines to treat the internal Kafka to Redpanda rebuild as a developer case study, because no external adopter is involved.",
"Routes the internal rebuild to samber/developer-relations-skills@engineering-blog-post by name.",
"Identifies the teammate's promo-packet piece as a personal case study whose hero is the author.",
"States explicitly that this skill inverts that framing, because a developer case study's hero is the adopter and not the author.",
"Does not silently apply the customer case study spine to either piece.",
"Distinguishes both from an ongoing progress-as-it-happens story, which routes to samber/developer-relations-skills@build-in-public.",
"Says the routing out loud rather than producing the requested artefacts anyway.",
"Notes the 40% cost drop still needs an instrument and a measurement window wherever it is published.",
"Does not invent a customer or external adopter to make the case study framing work."
]
},
{
"id": 12,
"prompt": "Marketing wants to run our Coastal Freight study as a paid LinkedIn ad and stick it on the homepage carousel. We published it in March of the year before last. Their engineer who gave us the quotes, Sam Oduya, left them about a year ago I think. Also our CSM mentioned Coastal's renewal is looking shaky. Can we ship it Friday?",
"expected_output": "A refusal to reuse it as-is: re-verification required past the roughly 18-month convention, the churn risk named, separate permission required for the paid and homepage surfaces, and the Friday date made conditional.",
"files": [],
"expectations": [
"Refuses to reuse the study without re-verification, because it is past the roughly eighteen-month mark.",
"States that eighteen months is a working convention rather than a measured shelf life, and should be shortened for adopters who ship fast or churn.",
"Names what re-verification checks: whether the adopter migrated away, whether the numbers have moved, and whether the quoted engineer has left.",
"Flags Sam Oduya's departure as a reason the quote and its attribution need re-confirming.",
"Flags the shaky renewal as a churn risk and states that publishing a study for a customer who churned is a reputational cost far larger than the study's value.",
"Recommends unpublishing rather than leaving the study up if the customer has in fact churned.",
"States that republication in a paid or advertising context commonly needs its own permission, separate from the original approval.",
"Treats the homepage carousel as a separate surface that may need its own permission too.",
"Refuses the Friday ship date outright or makes it conditional on the re-verification and the new permissions landing first.",
"Recommends dating every study at publication and setting its re-verification date then, rather than discovering staleness at reuse time."
]
},
{
"id": 13,
"prompt": "Our CMO wants a number on the case study program before the next budget cycle. She is asking me to attribute closed-won revenue to each study, we published six last year. My plan was to take every deal that touched a study in the CRM and split the revenue across the studies it touched. Sound right? And what should the dashboard show her?",
"expected_output": "A refusal to attribute revenue to individual studies, with a replacement set of signals about whether studies move evaluations forward, framed as things to weigh rather than targets, plus an honest statement of what the published research does and does not measure.",
"files": [],
"expectations": [
"Refuses to attribute closed-won revenue to a single case study.",
"Gives the reason: overclaiming attribution is the same credibility failure the artefact exists to avoid.",
"Rejects traffic as the measure of a study, in favour of whether it moved evaluations forward.",
"Proposes use in live deals: how often sales or solutions engineers actually send it, and at which stage.",
"Proposes read-through rate and clicks through to the artefacts the study links, such as docs, repository or architecture page.",
"Proposes inbound reference requests, meaning prospects asking to talk to that customer.",
"Proposes whether the adopter's own engineers amplify the study themselves.",
"Proposes coverage of the story bank, noting one credible study per major use case and adopter size beats five for the same profile.",
"States these are signals to weigh rather than targets to hit.",
"States that no published metric isolates case studies aimed specifically at developers as their own category.",
"Notes the general B2B technology-buyer research places vendor-produced case studies well behind product demos, free trials and prior experience with the product for buying-decision impact."
]
}
],
"trigger_queries": [
{
"query": "Write a case study about how Northwind moved their billing pipeline onto our workflow engine",
"should_trigger": true
},
{
"query": "We need a technical case study for the blog, the customer is a fintech running us in production",
"should_trigger": true
},
{ "query": "draft a customer success story for our developer site", "should_trigger": true },
{
"query": "Can you turn this interview transcript with their staff engineer into something publishable about their production rollout?",
"should_trigger": true
},
{
"query": "how do I get a reference customer to agree to be named in a write-up",
"should_trigger": true
},
{
"query": "our biggest user agreed to be featured, what do I ask them on the call",
"should_trigger": true
},
{
"query": "legal will not let us name the company in the write-up, what are our options",
"should_trigger": true
},
{
"query": "four customers said yes to being featured, which one do we do first",
"should_trigger": true
},
{
"query": "is this story even worth writing, they are still evaluating us",
"should_trigger": true
},
{
"query": "the customer never measured their old system, can we still publish the story",
"should_trigger": true
},
{
"query": "what should go in a developer adoption story besides the numbers",
"should_trigger": true
},
{
"query": "turn the approved Acme study into a one-pager for the sales team",
"should_trigger": true
},
{
"query": "how long before we should re-verify a published customer story",
"should_trigger": true
},
{ "query": "our study reads like a testimonial, how do I fix it", "should_trigger": true },
{ "query": "write up how Acme uses us", "should_trigger": true },
{
"query": "we want proof that engineers actually run this in production, help me produce it",
"should_trigger": true
},
{
"query": "who do I need approval from before publishing a customer's metrics",
"should_trigger": true
},
{ "query": "the customer struck all our numbers in review, what now", "should_trigger": true },
{
"query": "interview guide for talking to a customer engineer about their migration onto us",
"should_trigger": true
},
{
"query": "what does a limitations section look like in a customer story",
"should_trigger": true
},
{ "query": "our contract has a logo clause, does that cover quotes", "should_trigger": true },
{
"query": "help me write the results section with the measurement method included",
"should_trigger": true
},
{ "query": "how many numbers should a customer story carry", "should_trigger": true },
{
"query": "should I annualise the one-month savings figure in the write-up",
"should_trigger": true
},
{
"query": "the engineer said it is way faster, how do I turn that into something publishable",
"should_trigger": true
},
{
"query": "we want a published account of a real production deployment by one of our users",
"should_trigger": true
},
{ "query": "draft the approval email for the customer story review", "should_trigger": true },
{ "query": "what do security reviewers usually cut from these write-ups", "should_trigger": true },
{
"query": "an OSS maintainer who uses our SDK wants to be featured, how is that different from an enterprise",
"should_trigger": true
},
{
"query": "should we chase the big insurer story or the three startups",
"should_trigger": true
},
{ "query": "our study has no alternatives section, does that matter", "should_trigger": true },
{
"query": "what do I do when the customer rewrites their quote into marketing language",
"should_trigger": true
},
{
"query": "we have telemetry showing their error rate dropped, can we publish that as their number",
"should_trigger": true
},
{
"query": "help me qualify whether this deployment can carry a published story",
"should_trigger": true
},
{ "query": "how do I stop this reading like vendor copy", "should_trigger": true },
{ "query": "build the evidence ledger for these claims before I draft", "should_trigger": true },
{
"query": "the customer's comms team wants to own the narrative, how do I handle that",
"should_trigger": true
},
{
"query": "how do I structure a story about a customer's migration off cron onto our scheduler",
"should_trigger": true
},
{
"query": "we published a story last year and the customer just churned",
"should_trigger": true
},
{ "query": "case study outline for a developer audience", "should_trigger": true },
{
"query": "what is a good headline for a customer story about cutting build times",
"should_trigger": true
},
{ "query": "can I quote their VP without written permission", "should_trigger": true },
{
"query": "the migration story is great but they will not share absolute costs",
"should_trigger": true
},
{ "query": "how do I measure whether our customer stories are working", "should_trigger": true },
{
"query": "our CMO wants revenue attributed to each published customer story",
"should_trigger": true
},
{
"query": "a user wrote a blog post about us, can we turn that into a formal story",
"should_trigger": true
},
{
"query": "what makes engineers actually believe a vendor-published story",
"should_trigger": true
},
{
"query": "need proof points for our docs showing who runs this at scale and how",
"should_trigger": true
},
{
"query": "we want to publish how a customer built on our API, they are fine with it",
"should_trigger": true
},
{
"query": "how do I ask a customer's engineer about what broke during rollout",
"should_trigger": true
},
{ "query": "should the manager and the engineer be on the same call", "should_trigger": true },
{
"query": "the deadline is in three weeks, does the enterprise candidate still work",
"should_trigger": true
},
{ "query": "we want one credible story per use case, how do I plan that", "should_trigger": true },
{ "query": "the draft has seamless and game-changing all over it", "should_trigger": true },
{
"query": "how do I attribute a quote when the company cannot be named",
"should_trigger": true
},
{
"query": "the customer changed three things at once, how do I write the results",
"should_trigger": true
},
{
"query": "what is the difference between a case study and a testimonial for a dev tool",
"should_trigger": true
},
{
"query": "my write-up about a user's deployment needs a cost section, what goes in it",
"should_trigger": true
},
{ "query": "how do I get numbers I can publish out of a customer call", "should_trigger": true },
{
"query": "which of our adopters gives us the most published proof per hour",
"should_trigger": true
},
{
"query": "draft the section on why they picked us over the alternatives",
"should_trigger": true
},
{
"query": "the account team wants something to send a stalled deal that proves peer usage",
"should_trigger": true
},
{ "query": "we interviewed them but never got the manager, is that a problem", "should_trigger": true },
{
"query": "how do I document a user's production setup so other engineers can judge it",
"should_trigger": true
},
{
"query": "write an engineering blog post about how we rebuilt our own ingestion layer",
"should_trigger": false
},
{ "query": "case study for my design portfolio", "should_trigger": false },
{
"query": "help me write a portfolio case study about the dashboard I redesigned",
"should_trigger": false
},
{
"query": "turn our approved customer story into a conference talk outline",
"should_trigger": false
},
{
"query": "script a video walkthrough of the approved customer story",
"should_trigger": false
},
{ "query": "prep me for a podcast interview about our product", "should_trigger": false },
{
"query": "pitch our customer story to a journalist at a trade publication",
"should_trigger": false
},
{
"query": "schedule our content for next quarter across the blog and the newsletter",
"should_trigger": false
},
{ "query": "write the release notes for v2.4", "should_trigger": false },
{ "query": "write the upgrade guide from v1 to v2", "should_trigger": false },
{
"query": "write a tutorial showing how to build a webhook consumer with our SDK",
"should_trigger": false
},
{ "query": "our quickstart takes 40 minutes, fix it", "should_trigger": false },
{ "query": "should I publish our MRR publicly every month", "should_trigger": false },
{ "query": "start a weekly devlog for my open-source project", "should_trigger": false },
{
"query": "plan the launch of our open-source project on Hacker News",
"should_trigger": false
},
{ "query": "who are our developer segments and how do they differ", "should_trigger": false },
{
"query": "map the developer journey from first docs visit to first deploy",
"should_trigger": false
},
{ "query": "which devrel metrics should we report to the board", "should_trigger": false },
{ "query": "build a dashboard for our devrel analytics", "should_trigger": false },
{ "query": "how should we split next year's devrel budget", "should_trigger": false },
{ "query": "design a developer champions program", "should_trigger": false },
{ "query": "our Discord is dead, how do we revive it", "should_trigger": false },
{ "query": "write a CFP abstract for a Kubernetes conference", "should_trigger": false },
{ "query": "should we sponsor this conference or skip it", "should_trigger": false },
{ "query": "restructure our docs information architecture", "should_trigger": false },
{
"query": "our code samples are inconsistent across languages, standardise them",
"should_trigger": false
},
{ "query": "improve our docs ranking for rate limit python", "should_trigger": false },
{ "query": "find the keywords developers search for in our space", "should_trigger": false },
{
"query": "rewrite our README so the project is understandable in 30 seconds",
"should_trigger": false
},
{ "query": "triage 400 open issues in our repo", "should_trigger": false },
{ "query": "pick a licence for our new library", "should_trigger": false },
{
"query": "set up governance now that we have maintainers outside the company",
"should_trigger": false
},
{ "query": "design the onboarding path for first-time contributors", "should_trigger": false },
{ "query": "how do we price our developer tool", "should_trigger": false },
{ "query": "open core or BSL for our business model", "should_trigger": false },
{ "query": "hire our first developer advocate", "should_trigger": false },
{ "query": "how do I get promoted from advocate to head of devrel", "should_trigger": false },
{
"query": "write job posts that attract senior engineers to our company",
"should_trigger": false
},
{ "query": "optimize my GitHub profile README", "should_trigger": false },
{
"query": "which podcasts and newsletters should I follow in devrel",
"should_trigger": false
},
{ "query": "should we push our spec through a standards body", "should_trigger": false },
{
"query": "compare our developer experience against two competitors",
"should_trigger": false
},
{
"query": "structure our AGENTS.md so coding agents use our library correctly",
"should_trigger": false
},
{
"query": "write a troubleshooting page for the 429 errors people keep hitting",
"should_trigger": false
},
{ "query": "plan a live demo for our keynote that will not break", "should_trigger": false },
{ "query": "start a monthly meetup program in three cities", "should_trigger": false },
{ "query": "our GitHub Sponsors page is not converting", "should_trigger": false },
{ "query": "which registries should we publish our SDK to", "should_trigger": false },
{
"query": "write a case brief for the security incident we handled last week",
"should_trigger": false
},
{ "query": "teach me the Harvard Business School case method", "should_trigger": false },
{ "query": "write up a patient case report for the journal", "should_trigger": false },
{ "query": "prepare a legal case summary for the deposition", "should_trigger": false },
{ "query": "write a UX case study for my Behance profile", "should_trigger": false },
{ "query": "moderation policy for our community Slack", "should_trigger": false },
{ "query": "launch a community forum for our users", "should_trigger": false },
{
"query": "how should our devrel team be structured once we are 40 people",
"should_trigger": false
},
{
"query": "build the go-to-market plan for our developer-first product",
"should_trigger": false
},
{ "query": "write a testimonial request email for our G2 page", "should_trigger": false },
{
"query": "design our developer certification and education program",
"should_trigger": false
},
{
"query": "how do we build an ecosystem of integrations around our API",
"should_trigger": false
},
{ "query": "what is our three-year devrel strategy", "should_trigger": false },
{ "query": "brief our AE for a customer reference call next week", "should_trigger": false },
{
"query": "help me write a business case to buy this observability tool",
"should_trigger": false
},
{
"query": "draft the internal post-mortem for our failed migration last quarter",
"should_trigger": false
}
]
}
references/approval-and-anonymization.md›
# Approval and anonymization
Approval decides which version of the story is writable, so open it before drafting. A study built on numbers the adopter will not clear has to be rewritten from scratch.
## Read the contract first
Standard SaaS terms often already grant the vendor a licence to use the customer's name and logo and to say publicly that they are a customer. Vercel's terms carry the clause at §16.4 ("Customer Name"), granting a non-exclusive, royalty-free licence to reproduce the customer's trademarks and logos in marketing materials and to indicate that they are a customer, subject to the customer's own trademark-usage guidelines.
That clause settles the logo wall. It settles nothing else.
None of the following is a trademark use:
- A quote.
- A metric.
- An architecture description.
- An account of how the customer's systems failed before.
Publishing any of them on the strength of a logo clause is how a reference relationship ends. Check the clause, then run the chain below for everything it does not cover.
Two practical consequences:
- The logo-wall question is usually already answered before you ask.
- A customer who says "we never approve case studies" may still be contractually fine with the logo, which keeps a lighter artefact available when the full story is refused.
## The consent chain
Four permissions, often four different holders. Ask at first contact who holds each and how long each takes. The delays below are working estimates, not measured norms - the structure itself matches how a real developer-focused company runs this in public: PostHog's own marketing handbook has the customer tagged for a fact check first, with legal and PR "sometimes" looped in after, not before (`posthog.com/handbook/marketing/customer-case-studies`).
| Permission | Usual holder | Typical delay |
| ------------------------------------- | ------------------------------------------- | ------------- |
| Being quoted and named, with title | The interviewed engineer | Immediate |
| Spending the team's credibility on it | Their manager | Days |
| Company name, logo, published wording | Communications or marketing | Days to weeks |
| Technical detail and metrics | Security, or legal for regulated industries | Weeks |
Enterprise adopters run the full chain. A startup collapses it to one or two people. An individual developer or OSS maintainer _is_ the chain - a message is enough, but ask explicitly whether their employer may be mentioned.
Get naming and logo permission in writing from someone who can actually grant it. A chat approval from the engineer does not bind their company.
What stalls a chain, independent of company size, is a vague ask. B2B case-study consultant Joel Klettke describes legal and PR reviewers needing something concrete to say yes or no to - "this is what they want to talk about, are we comfortable with this or with these metrics?" - rather than an open-ended request they have no way to bound. A story with no one accountable for moving it forward gets deprioritized rather than revisited, so naming an owner and a date matters more than the size of the ask (The Campaign podcast, 97th Floor, Feb 21, 2025).
## What review predictably strikes
Pre-redact these so the draft survives the first pass:
- Absolute infrastructure sizes and costs: node counts, cluster sizes, monthly spend, capacity headroom.
- Internal service names, codenames, ticket IDs, repository paths, dashboard URLs.
- Named competitors in the rejected-alternatives section.
- Incident specifics tied to a dated outage the company never publicly disclosed.
- Anything implying a security weakness in the before-state - the single most common deletion.
- Customer-of-the-customer names and any end-user data.
Substitutions that usually survive:
- Ratios instead of absolutes ("cut infrastructure cost by about a third").
- Failure described by mechanism instead of by incident ("retry storms could double-charge").
- Role descriptions instead of team names.
## Anonymization ladder
When naming is refused, descend one rung at a time rather than dropping the story.
1. Named company, named engineer with title. Full credibility.
2. Named company, unnamed engineer ("a staff engineer on the payments team"). Small loss.
3. Unnamed company with an identifying descriptor ("a top-five European mobility platform"), metrics intact. Noticeable loss; the numbers now carry the whole study.
4. Category descriptor only ("a fintech of roughly 200 engineers"), metrics intact. The floor for anything still called a case study.
5. Composite or pattern write-up, no single customer, no attributed quote. Not a case study - publish it as an engineering-pattern post and label it as one.
Never sharpen a descriptor until the company is identifiable while still claiming anonymity. That breaks the agreement in substance even if the name never appears, and it is the kind of failure that ends a reference relationship.
## Review mechanics
Send the full draft, never fragments - reviewers reading isolated quotes strike them for lack of context. Mark exactly what needs a decision:
- Each quote.
- Each metric.
- The architecture description.
- The company name.
- The logo.
- The limitations section.
Give a dated deadline and state the default: "if we do not hear back by the 14th, we publish the anonymised version without the cost figures." A deadline with no default is a deadline that slips.
Let the adopter edit their own quotes freely. Push back once when an edit turns a quote into vendor copy, with the original alongside, then accept their decision.
## Request template
Adapt tone to the relationship; keep the structure.
```
Subject: Case study draft for review - decisions needed by <date>
Hi <name>,
Attached is the full draft of the case study from our conversation on <date>.
Nothing is published until you approve it.
Please confirm or correct:
1. Company name and logo usage - currently: <named / anonymised as "...">.
2. Quotes - three, highlighted in yellow, transcribed verbatim. Edit freely.
3. Metrics - four figures, highlighted in blue. Each lists the dashboard and
window we attributed it to. Strike anything your team cannot vouch for.
4. Architecture section - please check technical accuracy; we drew it from
your diagram plus the call.
5. Limitations section - the migration effort and the parts you left on cron.
We keep this in because engineers trust a story that names its costs, but
it is yours to cut.
Who else needs to sign off on your side (security, legal, comms)? Happy to
send it to them directly.
If we have not heard back by <date>, we will hold publication and follow up
rather than publish anything unapproved.
<name>
```
## After approval
Keep three artefacts together:
- The written permission.
- The final approved text.
- The metric provenance sheet.
Any later dispute is settled from these.
Republishing in another format commonly needs its own permission, for example:
- Sales one-pager.
- Conference slide.
- Paid ad.
- Homepage logo wall.
Ask for the ones you know you want while the reviewer is already engaged.
Stories go stale. Re-verify anything older than roughly 18 months before reusing it - a self-set convention rather than a measured shelf life, and too long for an adopter in a fast-moving stack. By then:
- The adopter may have migrated away.
- The numbers may have moved.
- The quoted engineer may have left.
Publishing a study for a customer who churned is a reputational cost far larger than the study's value.
references/case-study-outline.md›
# Case study outline and worked examples
Section-by-section guidance for the spine in SKILL.md, plus positive/negative pairs.
Word budgets assume a 1,200-1,800 word study. They are self-set proportions, not measured norms - the three published vendor studies measured for this skill run about 1,650, 2,100 and 2,400 words. Scale them to the material and keep sections 4, 5 and 7 dominant.
## Contents
- Section guidance
- Worked examples
- One-page summary shape
- Quote handling
## Section guidance
**1. Headline outcome (~60 words).** The change and its shape, in the first screen. Lead with the delta, not with the customer's company description. A reader who bounces here read one sentence - make it the number.
**2. The adopter and the system (~120 words).** Enough to size the situation: what the company does, what the relevant service does, its scale, the surrounding stack. Skip the boilerplate "founded in 2014, headquartered in…" - it signals a marketing artefact within one line.
**3. Before-state and its cost (~250 words).** The old design and how it failed, in mechanism terms, plus what the failure cost in engineer time, incidents or blocked roadmap. This section is what makes a reader recognise their own system; vagueness here loses them for the rest of the piece.
**4. Why this technology (~200 words).** What else was evaluated - including building it in-house - and the property that decided it. Name at least one thing an alternative did better. A section where every alternative is uniformly worse reads as fiction and costs more trust than it buys.
**5. What they built (~400 words).** Architecture with named components, the SDK or language, the sequencing, and the domain constraints that shaped it (regulatory windows, retry caps, peak-hour limits). A before/after diagram pair carries more here than any paragraph. Include code only if the adopter's engineers wrote it and cleared it; do not manufacture snippets.
**6. Results (~200 words).** Two to four numbers, each with instrument and window. Put the measurement method next to the number, not in a footnote - a reader who does not trust the setup does not read the figure.
**7. What it cost and what is unsolved (~200 words).** Covers:
- Migration effort.
- Dual-running period.
- What broke.
- What was deliberately left behind.
- What still does not work.
- Who should not copy this.
Vendor-published studies routinely skip it, which is the cheapest differentiation available to you.
**8. What is next (~70 words).** Their roadmap for the system, in their words. Doubles as an honest signal that the story is not finished.
## Worked examples
**Headline outcome**
```
Bad: Acme is a leading provider of cloud-native retail solutions. After
partnering with us, Acme unlocked transformative efficiency gains and
dramatically improved reliability across their platform.
Good: Acme's checkout jobs used to fail on roughly 1 in 20 runs and needed a
manual replay every morning. Eight weeks after moving the pipeline onto
durable workflows, the failure rate sits at 0.1% and the morning replay
ritual is gone.
```
The bad version has no mechanism, no number, no instrument. The good one gives a before value, an after value, a window, and a human consequence a reader recognises.
**Before-state**
```
Bad: Their legacy system struggled to scale and created significant
operational overhead for the engineering team.
Good: Four cron jobs - notify, verify-notify, collect, verify-collect - each
retried against the same Postgres table with no shared state. When a
retry storm hit during a promotion, the jobs re-notified customers
already charged, and an engineer spent the next morning reconciling by
hand. That happened three times in Q1.
```
**Results with provenance**
```
Bad: Performance improved by over 300% and the team saved countless hours.
Good: Median end-to-end run time went from 42 minutes to 11 minutes, measured
on their Grafana pipeline dashboard over the four weeks before and after
cutover. The team estimates the removed manual replay saved about six
engineer-hours a week; that figure is their estimate, not instrumented.
```
Note the second number is explicitly downgraded rather than dressed up as measured.
**Limitations**
```
Bad: (section omitted)
Good: The migration took two engineers about seven weeks, five of them spent
on backfilling in-flight jobs rather than on the new pipeline. They ran
both systems in parallel for three weeks and paid double compute during
that window. Their batch reconciliation job stayed on cron: it runs once
a day, and the team saw no reason to move it. Teams whose jobs are
short, idempotent and already reliable would not get the same return.
```
**Limitations that are really a roadmap**
```
Bad: We plan to consolidate the orchestration layer into Python, and chat
approvals are on the roadmap for next quarter.
Good: The orchestration layer is Go; the team that maintains it writes Python
everywhere else, so every change to it goes through the two people who
know both. Approvals still happen outside the system - the integration
only posts notifications - so an on-call engineer still opens a second
tool to unblock a run.
```
Both describe the same two facts. The first tells the reader what the vendor hopes happens next; the second tells them what they would inherit on day one. Only the second is a limitation.
**Quote**
```
Bad: "This best-in-class solution has been a game-changer for our team,
enabling us to deliver value faster than ever." - VP of Engineering
Good: "It used to wake us up twice a week. I haven't touched the runbook since
March." - Priya N., Staff Engineer, Payments
```
The bad quote is unattributable to a human and unfalsifiable. The good one is specific, dated, and comes from the person who was paged.
## One-page summary shape
Derived from the approved study, never written independently:
- The headline outcome, verbatim from section 1.
- Adopter, industry, relevant scale - three lines.
- Three numbers with their instruments.
- One quote with name and title.
- One line naming the main trade-off. Keeping it in the short version is what stops the one-pager from reading like an ad.
- A single link to the full study.
## Quote handling
- Transcribe verbatim; trim only filler words, never rebuild a sentence.
- Mark cuts inside a quote with an ellipsis and never splice two answers into one quote.
- Attribute with the exact name and title confirmed on the call.
- Two quotes from different altitudes - implementer and owner - cover "it works" and "it changed how we operate".
- If the reviewer rewrites a quote into vendor register, push back once with the original, then accept their version: it is their voice to give.
- Never publish a placeholder quote. No approved quote means the study ships without one.
references/evidence-and-sources.md›
# Evidence and sources
Every number, threshold and structural claim this skill states, split into **sourced** (traceable to a named published artefact) and **self-set** (a working baseline rather than a published figure). Quote a self-set number externally only as "our working baseline", never as an industry standard.
## Contents
- Published studies compared
- Sourced claims
- Self-set baselines
- Named methods this skill borrows
## Published studies compared
Seven published case studies, in full. Small sample: treat the shapes as observed patterns, not as a benchmark.
| Study | Sections | Length | Attributed quotes | Costs/limitations disclosed |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ShareChat on Temporal (`temporal.io/resources/case-studies/sharechat`) | Customer, Challenge, Solution, Why Temporal, Scale, Results, What's Next | ~1,650 words | 2 (SDE-3 Payments; Engineering Manager Payments) | None |
| Duolingo on Temporal (`.../duolingo-temporal-nexus`) | Customer, Why Temporal, Challenge, Solution, Results, Takeaways | ~2,100 words | 0 | 3, all framed as roadmap: orchestration logic in Go while most workflows are Python, chat integration limited to notifications, an earlier manual copy step |
| Attentive on Temporal (`.../attentive-migrates-temporal-cloud-infra-cost-savings`) | Platform overview, scale/performance issues, migration, cost savings | ~2,400 words | 2 named (Software Engineering; Software Engineer), 2 unnamed team members | Yes: 8 engineering-months/year on self-hosted maintenance, a Black Friday/Cyber Monday capacity crisis, a sharded-MySQL persistence layer with version-upgrade risk, horizontal/vertical scaling that didn't resolve cluster limits |
| Snyk content scaling (`developerrelations.com/case-studies/snyk-content-scaling`) | Overview, Challenge, Opportunity, Solution, Outcome | not measured | 2 (Director of DevRel; Head of DevRel and Community) | Yes: six months of director time to establish the process, 8-9 week outsourced production cycle, outlining slower than planned |
| Marketplace monetisation the wrong way (`developerrelations.com/case-studies/failing-to-monetise-a-marketplace`) | Overview, From Value-Add to Revenue Generation, Upsetting Partners, Picking Up the Pieces, Reflecting on What Went Wrong, Value Exchange Not Value Extraction, Looking at What Went Well | not measured | Named practitioner throughout | Yes, the whole point: rushed announcement, two resignations, a 2,000-developer verification backlog |
| Grid Dynamics on Temporal, blog format rather than the case-study template (`temporal.io/blog/prototype-to-prod-ready-agentic-ai-grid-dynamics`) | Why a deep-research agent is required, LangGraph solution, Temporal as a solution, state management, error handling, scaling, architectural decoupling, conclusion | not measured | 0 (3 named engineer bylines, no quoted speech) | Yes, a full post-mortem on the prior architecture: race conditions, stale state, agents stuck with no clear reporting, "extremely costly to support, with no clear path to reducing that burden," brittle Kafka exactly-once semantics |
| Outreach on Honeycomb (`honeycomb.io/case-studies/outreach-engages-their-production-code-with-honeycomb`) | About, Environment, Goals, What They Needed, Primary Use-Case, The Bridge Into Observability, Beginning to Implement SLOs | ~2,200 words | 6 quotes, 1 named speaker (Software Engineer) | No explicit cost figure, but a genuinely mixed outcome: kept Wavefront, Cloudwatch and Datadog rather than replacing them, and explains a side-by-side evaluation against Jaeger (UX lost) instead of presenting Honeycomb as a silver bullet |
Read across the seven:
- The original vendor-published pair (ShareChat, Duolingo) carries the metrics and the quotes and almost no cost.
- The community-published pair (Snyk, marketplace) carries the costs and the failure.
- The three later additions (Attentive, Grid Dynamics, Outreach) are vendor-published yet disclose real costs or trade-offs anyway - proof a limitations section is achievable outside the community-published half, not just a theoretical option.
- The corpus still leans on one publisher's editorial voice: four of the seven are Temporal-published (ShareChat, Duolingo, Attentive, Grid Dynamics), though only three of those four (ShareChat, Duolingo, Attentive) use Temporal's dedicated case-study template - Grid Dynamics is a blog post co-authored by the customer's own engineers, a distinct genre. Widen past Temporal before trusting the spine shape as a cross-vendor norm.
All belong in one artefact.
A related but structurally different account, cited for context rather than folded into the corpus above: Daylight Security's own engineering blog describes migrating _off_ Temporal Cloud after per-schedule pricing made roughly 500 workflow-starts/second prohibitively expensive, concluding their "costs are now predictable and significantly lower" after self-hosting (Alon Gluzman and Guy Grinberg, `daylight.ai/blog/how-we-migrated-off-temporal-cloud-without-downtime`). It is not a vendor-published case study - it is the customer's own unvarnished account of a vendor's limitation, published on their own terms, and a reminder that the customer-authored version of a migration story can read very differently from the vendor-authored one.
## Sourced claims
- **The Challenge / Solution / Results spine is the category default.** Four independent instances: ShareChat and Duolingo above, `LeadMagic/gtm-skills@case-study-builder`, and `anthropics/knowledge-work-plugins@draft-content`, whose case-study template is title, customer overview, challenge, solution, results with metrics, customer quote, CTA.
- **Vendor studies quote hands-on engineers with real internal titles**, not executives - ShareChat's two quotes are an SDE-3 and an engineering manager, both inside the payments team that did the work.
- **Headline metrics live in the title.** Temporal's index of 15 studies puts the number in the link text: "99.9% reliability", "1 billion+ agent Actions per month", "four million daily video workflows", "100x".
- **Recurring metric shapes**: reliability rate before/after, monthly production volume, cycle-time collapse, adoption spread inside the customer, dated migration window. ShareChat carries all five.
- **Naming and logo rights are often already granted in the contract.** Vercel's Terms of Service §16.4 "Customer Name": "During the term of this Agreement, you grant Vercel a non-exclusive, royalty-free, fully-paid up license to use and reproduce your trademarks, trade names and logos in Vercel's marketing materials and website(s) and to indicate that you are a Vercel customer". That clause covers the logo and the fact of being a customer. It does not cover quotes, metrics, architecture detail or a narrative - those still need the consent chain.
- **A published case study can disclose what it cost and still ship.** The Snyk and marketplace studies above are the existence proof; the marketplace one is a named practitioner walking through his own failure.
- **"A case study without numbers is a testimonial"** - `LeadMagic/gtm-skills@case-study-builder`.
- **A developer-focused company's own public process confirms the customer-first, legal/PR-optional shape of the consent chain.** PostHog's marketing handbook has the customer tag reviewed on GitHub (or Google Docs) for a fact check, not a copy edit, then adds: "legal and PR teams will sometimes want to be looped in for approval as well." No day/week timeline is given - PostHog's own text: "Most people are excited to be featured and will sign off quickly." Source: PostHog Handbook, "Customer case studies," `posthog.com/handbook/marketing/customer-case-studies`.
- **Why approval chains stall is documented, even without hard timeline numbers.** Joel Klettke, a B2B case-study copywriting consultant, discusses this at length on The Campaign podcast (97th Floor, Feb 21, 2025): vague asks give legal and PR nothing concrete to approve, so bounding the ask ("this is what they want to talk about - are we comfortable with this or with these metrics?") speeds review; normalizing the request early, getting leadership visibility, and maintaining velocity all matter because a stalled story gets deprioritized rather than revisited. Source: `the-campaign.castos.com/episodes/building-a-case-study-growth-engine-from-one-off-to-always-on-w-joel-klettke-1`.
- **Vendor-produced case studies rank well behind first-hand product experience in B2B technology buying, but are not negligible.** TrustRadius's 2022 B2B Buying Disconnect Report (survey of 2,185 technology buyers, February 2022) lists vendor-produced case studies at 28% among "most impactful resources when making the decision" - behind product demos (71%), free trial/account (67%), prior experience with the product (67%) and user reviews (59%), but ahead of vendor-provided customer references, third-party publications, vendor marketing collateral and the vendor blog. This is a general B2B-technology-buyer figure, not isolated to developer-focused case studies specifically.
- **No published engagement metric isolates "case studies aimed at developers" as its own category.** SlashData's Q3 2023 Developer Nation survey (17,000+ developers; Bleona Bicaj, "The types of content developers prefer," Feb 21, 2024, `slashdata.co/post/the-types-of-content-developers-prefer`) reports format preference - long-form video 62%, long-form text 57%, social media 31% - but buckets case studies inside "long-form text" rather than reporting them separately. Contently's "First Engagement Benchmarks for Downloadable Documents" (May 19, 2016; 100,000+ decision-maker sessions; `contently.com/strategist/2016/05/19/report-engagement-benchmarks-downloadable-documents`) groups case studies with e-books, white papers and sales sheets as one category: average 13.4 pages, average engagement 2:03, 35% of readers under 30 seconds. Neither source separates case studies from its broader bucket.
## Self-set baselines
Working baselines, not published figures.
- **1,200-1,800 words** for a full study. Chosen to sit just under the three measured examples (1,650, 2,100 and 2,400 words) while adding a limitations section none of them fully carries.
- **Per-section word budgets** in `case_study_outline.md`. Proportions, not measurements - scale them to the material.
- **Two to four numbers** in the results section. The published studies carry more; fewer well-sourced numbers survive review better.
- **Five qualification gates** and the **seven-check publication gate**. Both are binary checklists, not an industry standard.
- **Roughly 18 months** before a study needs re-verification. A convention, not a measurement - pick a shorter window for fast-moving adopters.
- **Four-permission consent chain.** The structure (customer first, legal/PR looped in as needed) matches PostHog's own public process and the mechanics Joel Klettke describes, sourced above. The **typical delays** (immediate / days / days-to-weeks / weeks) remain estimates - no source found gives a quantified per-step timeline, only qualitative confirmation of why each step can stall.
- **The five-rung anonymization ladder.** Self-set, not a published model.
## Named methods this skill borrows
- **Challenge / Solution / Results (CSR).** The category default spine, sourced above. This skill keeps it and adds three sections it never carries: alternatives rejected, metric provenance, limitations.
- **The Mom Test (Rob Fitzpatrick).** Its core interview rule - ask about specifics that already happened, not opinions or hypotheticals - is exactly what turns "it's much faster now" into "42 minutes to 11 minutes on the Grafana dashboard". The book targets discovery interviews with prospects; borrow the questioning discipline, not its scope.
references/source-interview-guide.md›
# Source interview guide
How to prepare, run and mine the interview a technical case study is built from. The call is the whole raw material: a study cannot be rescued in editing if the interview produced adjectives instead of mechanisms and numbers.
## Table of Contents
- [Before the call](#before-the-call)
- [Recording](#recording)
- [Borrow the Mom Test discipline](#borrow-the-mom-test-discipline)
- [Question ladder](#question-ladder)
- [Manager or platform-owner add-ons](#manager-or-platform-owner-add-ons)
- [During the call](#during-the-call)
- [After the call](#after-the-call)
- [Disqualifying signals](#disqualifying-signals)
## Before the call
Reconstruct the story from what you already hold, then use the call to confirm and correct:
- Support threads and issues the adopter filed - the before-state pain, in their words, already timestamped.
- Migration pull requests, public repos, their changelog.
- Usage telemetry on your side: when volume moved, when error rates dropped.
- Account or community notes: who championed it, what nearly blocked it.
- Their own engineering blog, conference talks, job posts - often describes the surrounding stack.
Send an agenda and one warning: "bring the dashboard numbers from before and after". An engineer who has not looked at the old dashboard cannot produce a baseline from memory.
Book the implementing engineer for an hour, and their manager or platform owner separately for twenty minutes. In a joint call the hands-on voice defers, and the hands-on voice is the one readers trust.
## Recording
Ask for consent to record at the start of the call, not in advance email only, and confirm it on the recording. Keep the transcript until publication plus the approval file. Verbatim quotes are the artefact's backbone, and paraphrase drifts toward vendor register - precisely what a technical reader detects.
## Borrow the Mom Test discipline
Rob Fitzpatrick's _The Mom Test_ was written for discovery interviews with prospects, but its central rule transfers exactly: ask about specifics that already happened, never about opinions or hypotheticals.
```
Weak: "Was it much faster?" - invites a compliment.
Strong: "What did the dashboard read the week before cutover, and what does
it read now?" - produces a number you can publish.
```
Every rung below is phrased that way on purpose.
The scope does not transfer - you are not learning whether the product is wanted, you are documenting a deployment that already happened. Take the questioning discipline and leave the framework's discovery goals behind.
## Question ladder
Run in order; each rung needs the previous one concrete.
**1. System context**
- What does this service do, and where does it sit in your architecture?
- What scale does it run at - requests, jobs, data volume, team size?
- What else is in the stack around it?
**2. Before-state**
- What was in place before, and who built it?
- How did it fail, and how often?
- Who got paged, and what did they do at 3am?
- Show me the shape of the old design - draw it if easier.
**3. Cost of the before-state**
- How much engineering time went into keeping it alive?
- What did it block on the roadmap?
- Did it ever cost revenue, customers, or an SLA?
**4. Trigger**
- What made this worth fixing _now_ rather than last year?
- Was there a specific incident, deadline or growth threshold?
**5. Alternatives**
- What else did you evaluate, including building it yourselves?
- Why was each rejected - and what did each one do better?
- What almost made you choose differently?
**6. Implementation**
- Walk me through what you built, component by component.
- What order did you do it in, and how long did each phase take?
- Who worked on it, and what were they doing instead?
- What surprised you - good or bad?
- What did you have to change in the surrounding system?
**7. Numbers**
- What did the key metric read before, and what does it read now?
- Which dashboard, log or bill does that come from?
- Over what window, and is it steady or still moving?
- Who on your team can confirm these numbers if someone asks?
**8. What it cost**
- How long was the migration, in engineer-weeks?
- Did you run both systems in parallel, and for how long?
- What broke during rollout?
- What did the team have to learn, and how long did that take?
**9. What is still unsolved**
- What parts did you deliberately not move, and why?
- What still does not work the way you want?
- What would you do differently starting today?
- Who should _not_ copy this setup?
**10. Advice to a peer**
- If an engineer at a similar company asked you about this over coffee, what would you tell them?
- What do you wish someone had told you before you started?
Rung 10 is where the publishable quote usually appears, because the engineer stops reporting and starts explaining.
## Manager or platform-owner add-ons
- What did this change about how your team operates?
- How did you justify the spend or the time?
- What would have happened if you had done nothing?
- How many teams use it now, and how did that spread?
## During the call
- Ask for the mechanism, never the adjective. "Faster" gets one follow-up: "faster from what to what, measured where?" If the second answer is still vague, note it as a qualitative claim and move on rather than inventing precision.
- Let silence run. The most useful admissions land three seconds after the answer you thought was finished.
- Read back numbers as you capture them, including the instrument, and confirm on the recording.
- Confirm name spelling and exact job title on the call. Titles change and reviewers correct them late.
- Flag the two or three sentences worth publishing as they happen: "that line about being paged twice a week - can we quote that?"
- Note anything the engineer marks as sensitive; it saves a round with their security reviewer.
## After the call
- Write the evidence ledger the same day: claim, evidence class, instrument, who can re-derive it.
- Send a short thank-you that restates the numbers you captured and asks for a correction if any are wrong. Errors surface here far more cheaply than in legal review.
- Ask for the architecture diagram they already have internally. Redrawing from memory is where most technical inaccuracies enter.
## Disqualifying signals
Stop and re-scope the artefact when you hear:
- "We're still evaluating it" - not production, no story yet.
- "We never really measured the old system" - no baseline, so no delta claim.
- "You'd have to ask marketing whether we can say that" and nobody has engaged them - handle approval before writing.
- "That was on our fork" or "we're on the unreleased build" - no reader can reproduce it.
- Every number comes from your dashboards and the customer cannot confirm any of them.
- The engineer will not be quoted and nobody else will either - it becomes an anonymised pattern write-up.
SKILL.md›
---
name: developer-case-study
description: Turns a customer's real production deployment into a technical case study engineers believe - measured numbers tied to how they were measured, before-and-after architecture, published limitations, and cleared naming and quote approval. Use whenever the user mentions a customer case study, a technical case study, a developer adoption or success story, a reference customer, or wants to turn a user interview, migration or production rollout into published proof - even if they only say "a post about how Acme uses us". Do NOT use for a post about your own system - use samber/developer-relations-skills@engineering-blog-post; for your own project's ongoing progress use samber/developer-relations-skills@build-in-public.
license: MIT
metadata:
author: Samuel Berthe
version: "1.0.1"
---
# 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](./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](./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](./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](./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](./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-outline.md) for the per-section guidance and worked positive/negative examples before drafting. The examples there (Acme, the Grafana figures) are invented illustrations, not measured cases - never cite them as evidence.
## Limitations are the differentiation
A limitation is a cost the reader would inherit, not a plan.
```
Roadmap: "We plan to consolidate the two languages."
Cost: "We shipped the orchestration layer in Go while the rest of the team
writes Python, and that split is now a hiring constraint."
```
One of the compared studies carries three of the former and none of the latter - do not accept that trade.
The gap is a publisher's choice, not a genre constraint. Across the four compared studies - a small sample, and both vendor ones from the same vendor:
- The vendor-published pair discloses no cost at all.
- The community-published pair discloses costs and a failure openly, one of them a named practitioner walking through his own botched launch.
Section lists and sources: [./references/evidence-and-sources.md](./references/evidence-and-sources.md).
Fill the section from the interview:
- Migration effort in engineer-weeks.
- The dual-running period.
- What broke during rollout.
- What the team retrained on.
- Which workloads they deliberately did not move.
- What still does not work.
State who should _not_ copy this architecture.
- Customer strikes the whole section: the study is weaker but still shippable.
- Customer strikes it _and_ the alternatives section: you are publishing an advertisement. Tell the owner plainly so it gets framed as one.
## Approval track
Read the contract's publicity clause before asking anyone for anything. Standard self-serve SaaS terms often already license the customer's name and logo and the statement that they are a customer - Vercel's terms carry such a clause, quoted verbatim in [./references/approval-and-anonymization.md](./references/approval-and-anonymization.md).
The clause grants nothing else:
- No quote.
- No metric.
- No architecture description.
- No narrative about how the customer runs their systems.
Ask for exactly what it leaves open.
Four permissions remain, often held by four different people:
- The engineer's consent to be quoted.
- Their manager's consent to spend team credibility.
- Communications sign-off on company name and logo.
- Security or legal review of the technical detail.
Ask who holds each at first contact.
Pre-redact what security review predictably strikes:
- Absolute infrastructure sizes and costs.
- Internal service names, ticket IDs, dashboard URLs.
- Competitor names in the rejected-alternatives section.
- Anything implying a security weakness in the before-state.
Send the full draft with the decisions marked, a dated deadline, and a stated default.
When naming is refused, descend the anonymization ladder one rung at a time rather than dropping the story:
1. Named company and engineer.
2. Named company, unnamed engineer.
3. Unnamed company with an identifying descriptor.
4. Category descriptor only.
5. Pattern write-up with no customer.
Each rung costs credibility, and the last one is no longer a case study.
This ladder is deliberately not ranked by effort or efficiency: the rungs are not alternatives anyone picks between, since every one below the top is cheaper only because someone refused the one above it. Take the highest rung approval allows, and read the descent as loss, not as a trade-off.
Full ladder, redaction classes and a request template: [./references/approval-and-anonymization.md](./references/approval-and-anonymization.md).
## Humanizer pass
Run the prose through your preferred humanizer skill before the gate. Model-flavoured filler reads as vendor copy, which is the register this artefact most needs to avoid.
Preserve exactly as written: every quote, every number, version strings, component names and the architecture description. A humanised quote is a fabricated quote.
## Publication gate
Seven checks - a working gate, not a published standard. Hold the study until all seven pass. Report which check failed and what you changed, then re-check.
1. **Every claim classified** - measured, partially measured, reported, or the engineer's marked opinion. No exceptions.
2. **Every number has an instrument and a window** stated or one click away.
3. **At least one limitation** published, specific enough that a reader could decide against you on it.
4. **Alternatives section present**, naming what was rejected and why.
5. **Every quote verbatim** from the transcript, attributed with a confirmed name and title.
6. **Approval evidence on file** for company name, logo, quotes, and security review.
7. **Zero unsupported superlatives.** Any "seamless", "effortless", "game-changing" is either backed by a number in the study or gone.
Then two human reads happen before publishing:
- The interviewed engineer confirms technical accuracy.
- Someone outside the account checks it is comprehensible without insider vocabulary.
## Derivative versions
One approved study feeds several artefacts. Ask which are needed _before_ approval, so permission covers them, and build them in reuse-per-hour order - every rung below reuses material the approved study already cleared, so the ranking is about where the reuse lands, not about writing effort:
1. Documentation cross-link - near-zero: a "who uses this and how" pointer from the relevant page, sitting where an evaluator already reads.
2. One-page summary for sales - an hour: outcome, three numbers, one quote, and no CTA on every section. Highest value of the four wherever a sales motion exists at all, and worthless where none does - which is exactly when to skip it rather than rank it.
3. Community post - an hour plus the engineer's willingness: their own words under their own name, which travels further than anything published under yours, and which only they can authorise.
4. Conference or webinar material - a day, and dependent on a slot existing. The architecture before/after is already a slide, so the marginal cost is low, but nothing here pays until the talk is accepted.
File the study's atoms - each metric, each quote, the architecture diagram - into a proof library alongside the narrative, with a public/private flag. Assets built later pull from the atoms; nobody re-reads a 1,500-word study to find one number.
Republication in a paid or ad context usually needs its own permission. Re-verify any study older than roughly 18 months before reusing it - a self-set convention, not a measured shelf life; shorten it for adopters who ship fast or churn.
## Failure modes
| Symptom | Cause | Fix |
| ------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Reads like a testimonial | Only sections 1, 2, 6, 8 have material | Go back for alternatives, architecture, cost - or publish a quote card |
| Customer strikes half the numbers | Metrics never had provenance | Rebuild each metric with instrument and window, resubmit |
| Approval stalls for weeks | Review chain engaged after drafting | Open the approval track at first contact; set a dated default |
| Engineers dispute it publicly | Architecture written from vendor assumption | Have the interviewed engineer confirm the technical sections |
| Quotes sound like marketing | Paraphrased instead of transcribed | Restore verbatim from the recording; accept the customer's own edits |
| Story dies after the interview | Qualification gates skipped | Run the gates before booking the call |
| Numbers overclaim | Product credited for a multi-change rollout | Name everything else that changed in the same window |
| Customer disputes an "approved" study | The contract's logo clause read as blanket approval | Treat the clause as name and logo only; get quotes, metrics and narrative separately |
| Limitations section says nothing | Roadmap items accepted as costs | Ask again for engineer-weeks, dual-running, what broke - a plan is not a cost |
| Churned customer's study still live | No re-verification date set at publication | Date every study, re-verify on schedule, unpublish rather than leave it up |
## Measurement
Judge a study on whether it moved evaluations forward, not on traffic. No published metric isolates case studies aimed specifically at developers: general B2B-technology-buyer research puts vendor-produced case studies well behind product demos and free trials for buying-decision impact (see [./references/evidence-and-sources.md](./references/evidence-and-sources.md)), but nothing narrower than that exists. Treat the signals below as things to weigh, never targets to hit:
- Use in live deals: how often sales or solutions engineers actually send it, and at which stage.
- Read-through rate and clicks to the artefacts it links (docs, repository, architecture page).
- Inbound reference requests - prospects asking to talk to that customer.
- Whether the adopter amplifies it themselves; a story the customer's own engineers share is one they stand behind.
- Coverage of the story bank: one credible study per major use case and adopter size beats five for the same profile.
Do not attribute revenue to a single case study. Overclaiming attribution is the same credibility failure the artefact exists to avoid.
## References
- samber/developer-relations-skills@tech-talk-outline - turning an approved study into a stage talk
- samber/developer-relations-skills@technical-video-script - video retellings of an approved study
- samber/developer-relations-skills@tech-podcast-interview-prep - podcast retellings of an approved study
- samber/developer-relations-skills@devrel-content-calendar - scheduling a story bank across a quarter
- samber/developer-relations-skills@tech-press-relations - pitching an approved case study to a journalist as a press story
- [./references/source-interview-guide.md](./references/source-interview-guide.md) - pre-call preparation, question ladder, quote capture
- [./references/case-study-outline.md](./references/case-study-outline.md) - section-by-section outline and worked examples
- [./references/approval-and-anonymization.md](./references/approval-and-anonymization.md) - consent chain, redaction classes, anonymization ladder, request template
- [./references/evidence-and-sources.md](./references/evidence-and-sources.md) - the published studies behind the spine, sourced versus self-set thresholds