case-study-builder

Case Study Builder

Produces a Tiger Data "Community Member Spotlight" case study from a customer interview transcript. The output is a formatted .docx file with an embedded architecture diagram and a pull quote table.

---

Before You Start: Read Two Reference Files

Read both of these before writing a single word of the case study:

1. references/wabl-principles.md — Tiger Data writing standards. Every sentence must pass the WABL filter before the document ships.
2. references/case-study-format.md — The section structure, styling constants, and annotated guidance for each section of the document.

Also read the docx skill (find the docx SKILL.md in your available skills) before generating the .docx. The docx skill contains the exact docx-js patterns required to produce a valid Word document.

---

Step 0: No Fly List check

Fetch the No Fly List before doing any work. This requires Tiger Den:

get_marketing_reference(slug: "no-fly-list")

If Tiger Den is not available (get_marketing_reference fails or the tool is not found), warn the user: "No Fly List check skipped — Tiger Den is not connected. Verify manually that no restricted customers are referenced in the output before publishing." Then proceed.

If Tiger Den is available, load the returned names as a hard constraint: if the customer featured in this case study appears on the No Fly List, stop immediately and inform the user that this customer cannot be publicly referenced. If a No Fly List name appears in the transcript or other source materials, omit it from all outputs.

---

Step 1: Gather Inputs

Collect the following from the user's message and conversation history:

Input	How to get it
Transcript (required)	Google Doc URL → google_drive_fetch; uploaded file → read from /mnt/uploads/; pasted text → use directly
Case Study Prep doc (optional)	Google Doc URL → google_drive_fetch. Contains pre-mapped answers to the 8 Tiger Data case study questions. Treat it as additional context — it does not replace the transcript.
Example case studies (optional)	If the user pasted example copy into the conversation, use it as the stylistic reference. Otherwise, follow the structure in references/case-study-format.md.

If the transcript is missing, ask for it before proceeding. Everything else is optional.

---

Step 2: Ask Two Clarifying Questions

Ask both at once. Do not start writing until you have answers.

Q1: First or third person? The case study can be written as the customer speaking in first person ("I built this because...") or as a third-person narrative ("Tacton's team built this because..."). The Tiger Data format supports both. First person is more personal and works well for technical founders. Third person is easier to edit and suits larger orgs with PR teams. Default to first person if the transcript is from a single technical founder.

Q2: Who is the primary reader? Options: (a) developers and engineers — emphasise architecture, data model, technical trade-offs; (b) technical buyers / VPs — emphasise ROI, team size, time-to-value; (c) general — balance both. Default to (a) if the transcript is highly technical.

---

Step 3: Extract from the Transcript

Read the full transcript carefully. Extract and organise the following before writing:

Company basics

• Company name, spokesperson name and title
• Industry, customer type, company size
• Product(s) being discussed

The problem

• What was painful or broken before Tiger Data?
• What did the old stack look like?
• Why was the old approach unsustainable?

Why Tiger Data

• How did they discover Tiger Data? (blog post, Reddit, colleague, etc.)
• What alternatives did they consider?
• What made Tiger Data the right choice? (specific criteria)
• What would self-hosting have cost them?

Architecture

• What are the named services, edge devices, brokers, APIs?
• What data flows where? In what order?
• What does Tiger Data specifically store? (data types, cadence)
• What other databases or platforms are in the stack, and what do they hold?
• How does data reach the customer-facing application?

Results and impact

• Quantified metrics: compression %, query speed, cost savings, uptime, time-to-deploy
• Customer impact stories: specific incidents, prevented failures, ROI moments
• Support / onboarding experience

Looking ahead

• Roadmap items the customer mentioned
• Scale targets, new data streams, future features

Direct quotes

• Collect every quote that is punchy, specific, and quotable. Prefer quotes that are concrete ("we went from 4 minutes to half a second") over abstract ("it's been great").
• Note the exact words. You will clean up false starts and filler words but must not change the meaning or put words in the customer's mouth.
• Capture the context, not just the quote. Read the lines before and after each quote. A quote can be word-accurate but context-wrong — if the customer said something to explain why a problem is inherently complex (not to describe a failure of the old stack), framing it as a pre-Tiger Data symptom is a misrepresentation. Note what the speaker was responding to when they said it.

---

Step 4: Generate the Architecture Diagram

Write a Python script using matplotlib to produce the architecture diagram. Save it as a PNG in the current working directory as architecture.png.

Design guidance is in references/architecture-diagram-guide.md. The short version:

• White background, dot grid, monospace uppercase labels — no coloured zone fills
• Organise components into columns: Edge → Ingestion → Storage → Application
• Draw boxes with FancyBboxPatch: bold label only, no body text, compact height (~0.68 units)
• Tiger Data gets an orange border (2.5 lw), embedded logo badge, and a bold summary line
• Arrows with ax.annotate: omit labels unless the protocol is non-obvious
• Column headers as bold monospace text above each group
• figsize=(8, 4.5), coordinate system 0–16 × 0–9, save at 180 dpi

Run the script and confirm the PNG exists before moving to the next step.

---

Step 5: Write the Case Study .docx

Writing directive: Rewrite in the first person voice of the customer primarily pulling direct language from the transcript. Incorporate the Product Marketing Context from Tiger Den into the narrative.

Follow the structure in references/case-study-format.md exactly. Use the docx skill patterns for all formatting — never raw unicode bullets, never inline \n, and always set explicit page size (US Letter: 12240 x 15840 DXA).

About the Company & Team Lead with the customer problem — what pain does the end user of this product experience, and why does it go unsolved today? Then explain how the product solves it, with specific technical mechanisms. Team/founding story goes last and should be brief (1-2 sentences). This section should read like a problem brief for a developer audience, not a company bio.

The Challenge Describe the state of the world before Tiger Data. Be specific about what was slow, what cost too much, what was operationally painful. If there was a prior stack (InfluxDB, MongoDB, a Postgres cluster they self-hosted), name it and explain why it didn't scale.

Architecture-First Decision / Why Tiger Data Explain how the customer found Tiger Data, what alternatives they considered, what the specific decision criteria were, and why they chose managed over self-hosted. Include the discovery story if it's interesting (a Reddit comment, a blog post from 2018, a colleague recommendation). This is often the most differentiated section — it shows the customer made a deliberate technical choice, not just the default one.

The [Product] Stack (architecture section) Describe the full data flow in prose, naming every service. Then embed the architecture diagram. Follow the diagram with a caption. Do not just list components — explain what each one does and why it sits where it sits.

Results Lead with the most impressive metric. Then tell the impact stories from the transcript in order of emotional weight. Include at least one concrete before/after story (e.g. "$3K fix prevented $350K in downtime"). Put a pull quote block after any section where you have a strong direct quote that reinforces the message.

Looking Ahead Forward-looking only. No summary of what was just said. One or two paragraphs about what the customer plans to build next and how Tiger Data enables it.

Recommended Pull Quotes A table at the end. 5 rows. Columns: the quote itself (attributed, with " - Name, Title, Company"), and a recommended use note (hero, social, support section, etc.). All quotes must be direct quotes from the transcript, lightly cleaned for readability.

---

Step 6: WABL Review Pass

Before finalising, run the WABL filter from references/wabl-principles.md:

• Remove all em dashes. Replace with a regular hyphen-space ( - ) or restructure the sentence.
• Scan for AI slop: "seamlessly", "robust", "cutting-edge", "transformative", "game-changing", "leverage", "harness the power of", "it's worth noting", "delve into"
• Confirm there is one clear message. If someone asks "what is this case study saying?" the answer should be one sentence.
• Confirm the About section does not start with the spokesperson's name and job title. It should start with the customer's problem.
• Confirm there is no recap conclusion. The Looking Ahead section should look forward, not summarise what was said.
• Read one paragraph aloud. Does it sound like a confident engineer who built this? If not, rewrite it.

---

Step 7: Validate and Deliver

Run the docx validation script from the docx skill against the output file:

python <path-to-docx-skill>/scripts/office/validate.py \
  <workspace>/{Company}_Case_Study.docx

All validations must pass before delivering. If they fail, unpack the XML, fix the issue, and repack using the docx skill's repair workflow.

Save the final file to the workspace/outputs directory and provide the user with a computer:// link.

---

Common Mistakes to Avoid

Starting the About section with the spokesperson. "I'm [Name], CTO of [Company]..." is a company bio opener. The reader does not yet know why they should care. Lead with the problem the customer faces, then introduce the product, then briefly note who built it.

Paraphrasing quotes instead of using them. If the transcript has "we went from nothing to first devices being installed in two months," use that. Don't write "they achieved rapid deployment." Direct quotes are the whole point of a case study.

Making up metrics. Only use numbers that appear explicitly in the transcript or prep doc. If a metric is approximate, say so ("close to 100 devices"). Never round up.

Skipping the discovery story. How the customer found Tiger Data is often the most interesting paragraph in the piece. A Reddit comment that led to a 2018 blog post that led to an architectural decision is a better story than "they evaluated several options."

Describing the architecture as a list. "We use X, Y, and Z" is forgettable. "X captures sensor readings and sends them to Y via MQTT. Y validates the device, applies calibration thresholds, and writes time-series data to Z" gives the reader a mental model they will actually remember.

Using a quote accurately but in the wrong frame. If the customer said "it'll never be a snap of the fingers" to explain why dashboard performance is inherently hard to optimise — not to describe a failure of the old stack — attributing it as evidence of pre-Tiger Data slowness is a misrepresentation even though the words are exact. Always check what question the speaker was answering when they said it.

Writing a generic Looking Ahead close. "Ready to expand their business at scale" says nothing. If the case study is about an architectural decision (single database, no split stack), the Looking Ahead section should land on what that decision means as the product scales — the specific complexity or cost problem that won't arise.