One onboarding problem, eight Claude Code workflows

pm-workflow-kit/
  CLAUDE.md                 product context and the rules for every task
  research/interviews/      8 transcripts, each with a six-line header
  evidence/                 data answers, competitor scans, a CSV export
  prd/  tickets/  releases/  updates/  learnings/
  skills/
    synthesize-interviews/
      SKILL.md              the steps, in order
      templates/summary.md  the shape of the output
  hooks/                    saves your corrections between sessions
  evals/                    the answers we expect (kept out of runs)

# Tallyboard onboarding project

Fictional sample project from the TAI Labs Week 2 PM workflows post. Tallyboard is a
made-up B2B reporting tool: a team connects a data source (Postgres, Google Sheets or a
CSV upload) and builds dashboards on it.

## Product context
- Customers are 10 to 2,000 person companies. Buyers are ops leads, founders, finance
  leads and data analysts. At larger accounts an IT admin approves data access.
- Onboarding: Signed Up, Created Workspace, Connected Data Source, Viewed First Report,
  Invited Teammate. These are also the Amplitude event names.
- Analytics: Amplitude project 866138. Mock data: every user id starts with `demo_`.

## Folders
- `research/interviews/` one transcript per file, each with a six-line header
- `research/summaries/` one summary per interview (written by the synthesis skill)
- `evidence/` data answers, competitor scans, CSV exports
- `prd/` PRD drafts and critiques
- `tickets/` tickets drafted from a PRD
- `releases/` past release notes, this release's changes, new notes
- `updates/` weekly notes and stakeholder updates
- `learnings/` what each session taught us
- `skills/` the workflows. Copy them into `.claude/skills/` to use them.
- `evals/` expected answers. Do not open `evals/` unless you are asked to run an eval.

## Rules for every task
- Never invent a quote. A quote must appear word for word in the file you cite.
- Never invent a number. Every number names its source: a file, or the Amplitude query.
- If you cannot find something, say so. Do not fill the gap with something plausible.
- Leave any section marked "PM fills this in" empty.
- Write the output to a file, not only to the chat, and say which file.

mkdir -p .claude/skills && cp -r skills/* .claude/skills/
claude

---
name: synthesize-interviews
description: Summarise each customer interview in research/interviews/ with a fixed template, then synthesise across all of them into themes with source counts and verbatim quotes. Use when asked what customers are struggling with, for interview themes, or for a research synthesis. Not for a single document or for market research.
---

# Synthesize interviews

## 1. Take stock
- List every file in `research/interviews/`. Say the total (M).
- Read each header. A file with no header is named and left out, not guessed at.

## 2. One summary per interview
For each file, fill `templates/summary.md` and save it to
`research/summaries/<same file name>`. Quotes are copied, never reworded.

## 3. Synthesise
Write `research/synthesis.md`:
- **Themes**: one sentence each, in the customers' words where possible, then
  `N of M interviews`, then one verbatim quote per supporting file, each followed by
  the file name in brackets, like: "quote" (2026-08-18-ops-lead-agency.md)
- Order themes by N, highest first.
- **Single observations**: anything only one file says. Never promote these to themes.
- **Disagreement**: where segments want the same thing for different reasons, give
  both sides with quotes. Do not pick a winner.
- **By segment**: one line per segment on what they care about most.
- **What this does not tell us**: sample size, who we did not talk to.

## 4. Check your own quotes
Run `python3 evals/check_quotes.py research/synthesis.md` if it exists. Otherwise
search each quote in the file you cited. Remove any quote that is not found
word for word, and say how many you removed.

claude mcp add -t http -s user Amplitude "https://mcp.amplitude.com/mcp"
# then, inside Claude Code:
/mcp
# sign in to Amplitude, then ask:
What Amplitude projects can I access?

---
name: answer-data-question
description: Answer a plain-English product data question with Amplitude (through the Amplitude MCP) or, if that is not connected, the CSV in evidence/. Writes an auditable answer to evidence/. Use for funnel, conversion, drop-off, segment or "how many" questions.
---

# Answer a data question

## 1. Pin the question
Restate it as: metric, population, time window. If one is missing, pick a sensible
default and say which one you picked.

## 2. Find real names first
- Amplitude: call get_amplitude_context, then search the taxonomy for the events and
  properties you need. Use names exactly as returned. Never guess an event name.
- No Amplitude: read the header row of `evidence/onboarding-events.csv` and use
  Python (the standard `csv` module is enough).

## 3. Run it, then cut it once
Run the headline query. Then break it down by at least one dimension that could
change the story (platform, acquisition source, error reason) before you conclude
anything. A headline with no breakdown is not an answer.

## 4. Write the answer
Save `evidence/<yyyy-mm-dd>-<short-slug>.md` using `templates/answer.md`. Every
number in it comes from a query in the "How we got this" section.

## 5. Flag what could be wrong
Small groups (under 30 users), missing labels in the result, and anything that
looks too clean.

---
name: competitor-scan
description: Read each URL in evidence/competitors.txt and build a comparison of how competitors handle onboarding and pricing, with the date checked and a verified column for the PM. Use for competitor pricing or feature comparisons.
---

# Competitor scan

1. Read `evidence/competitors.txt`: one URL per line, `#` lines are notes.
2. Open each URL. If a page will not load or needs a login, write "could not read"
   for that row. Never fill a row from memory: prices change and your memory is old.
3. For each competitor record: plans and prices exactly as shown on the page, whether
   there is a free plan or trial, what it says about connecting data or sample data,
   and whether view-only users cost less.
4. Write `evidence/competitor-scan-<yyyy-mm-dd>.md` with one table:
   `Competitor | Plan | Price as shown | Free option | Viewer pricing | Onboarding notes | Source URL | Checked on | Verified by PM`
   Leave "Verified by PM" empty.
5. Under the table, three bullets: what we could copy, what we should avoid, and what
   the pages did not tell us.

---
name: write-prd
description: Draft a PRD from the PM's brain dump plus the evidence already in research/ and evidence/, using templates/prd.md, then critique the draft. Use when asked to write, draft or review a PRD or spec.
---

# Write a PRD

## Draft
1. Read the brain dump the PM gives you (a file or the message).
2. Read `research/synthesis.md` and the newest files in `evidence/`.
3. Fill `templates/prd.md`. Save to `prd/<short-slug>.md`.
   - Every claim about users cites a file. Every number cites a file.
   - Leave **Success metrics** and **Launch date** empty. The PM fills those in.
   - If the brain dump and the evidence disagree, keep both and flag it in Open questions.

## Critique
Then review your own draft as a sceptical head of product and save
`prd/<short-slug>-critique.md`:
- Is the problem stated without the solution baked in?
- Who exactly is the user, and which segment is left out?
- Which claim has the weakest evidence?
- What is the cheapest version that would test the idea?
- What would make us stop?
Be specific. "Consider adding more detail" is not a critique.

# <feature name>

**Owner:** <PM>  ·  **Status:** Draft  ·  **Launch date:** PM fills this in

## Problem
<the user problem, no solution in it>

## Evidence
- Qualitative: <theme, N of M, file>
- Quantitative: <number, file>
- Market: <what competitors do, file>

## Who it is for
- Primary:
- Not for (this time):

## Goals
-

## Non-goals
-

## Proposed solution
<short, testable, in steps>

## Success metrics
PM fills this in.

## Risks
-

## Open questions
-

---
name: prd-to-tickets
description: Break an approved PRD in prd/ into engineering tickets with acceptance criteria, saved to tickets/. Optionally creates them in Linear or Jira through MCP after the PM approves the list. Use when asked for tickets, stories or a backlog from a PRD.
---

# PRD to tickets

1. Read the PRD the PM names. If it has no "Proposed solution" section, stop and say so.
2. Split the solution into tickets a single engineer could finish in under a week.
3. For each ticket write: title (verb first), why (one line, linked to the PRD
   section), acceptance criteria as Given / When / Then, out of scope, and open
   questions. Do not estimate: the team does that.
4. Add one ticket for analytics: the event or property we need to measure success.
5. Save to `tickets/<prd-slug>.md`, in the order they should be built.
6. Only if the PM says "create them" and a Linear or Jira MCP server is connected:
   create them as drafts in the team or project the PM names, then list the links.

---
name: release-notes
description: Turn this release's changes (releases/changes.md, or a GitHub commit or PR URL read with the gh CLI) into a user-facing release note in the voice of releases/past-notes.md. Use when asked for release notes, a changelog entry or a "what's new" post.
---

# Release notes

1. Read what changed: `releases/changes.md`, or for a URL run
   `gh pr view <url>` or `gh api repos/<owner>/<repo>/commits/<sha>`.
2. Read `releases/past-notes.md` and match its voice and length.
3. Write for the user, not the team:
   - A title in Title Case that names the benefit.
   - One to five short paragraphs: what changed, who it helps, how to use it.
   - No ticket numbers, internal names or code words. No promises about future work.
4. Leave out anything in the changes marked internal.
5. Save to `releases/<yyyy-mm-dd>-<slug>.md`.

---
name: stakeholder-update
description: Write the weekly stakeholder update from updates/notes-this-week.md and the newest evidence files. Use when asked for a weekly update, status update or leadership summary.
---

# Stakeholder update

Read `updates/notes-this-week.md` and the newest file in `evidence/`.
Write `updates/<yyyy-mm-dd>.md` with exactly four headings:

- **Shipped**
- **Blocked** (say who can unblock it)
- **What we learned** (one number, with its source file)
- **Next week**

Rules:
- Under 250 words.
- Write like a busy PM on a Friday, not a press release. No "leverage", "synergy",
  "excited to share" or "game-changer".
- If the notes do not say something, it does not go in.

"""UserPromptSubmit hook: when a prompt starts with a correction, save it.

Appends to learnings/corrections.md so the next session (and /session-learnings)
sees it. Always exits 0, so it never blocks your prompt.
"""
import datetime
import json
import os
import re
import sys

TRIGGER = re.compile(r"^\s*(correction:|no[,.]|that's wrong|thats wrong|wrong:|remember:)", re.I)

try:
    prompt = json.load(sys.stdin).get("prompt", "")
except Exception:
    sys.exit(0)

if TRIGGER.match(prompt):
    root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
    path = os.path.join(root, "learnings", "corrections.md")
    os.makedirs(os.path.dirname(path), exist_ok=True)
    stamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M")
    with open(path, "a", encoding="utf-8") as f:
        f.write(f"- {stamp}: {prompt.strip()}\n")
sys.exit(0)

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/hooks/log-correction.py\""
          }
        ]
      }
    ]
  }
}

---
name: session-learnings
description: At the end of a working session, save what worked, what went wrong, decisions and corrections to learnings/, and propose (not make) changes to CLAUDE.md or skills. Use when the user says "wrap up", "save learnings" or ends a session.
---

# Session learnings

1. Look back over this session.
2. Write `learnings/<yyyy-mm-dd>.md` with:
   - **What worked**: steps or prompts worth repeating.
   - **What went wrong**: mistakes, including yours, and how they were caught.
   - **Decisions**: what was decided and why, in one line each.
   - **Corrections**: anything the user corrected. Also copy in any lines from
     `learnings/corrections.md` added today.
3. Propose edits: for each lesson that should change future behaviour, show the exact
   line you would add to CLAUDE.md or to a skill. Do not apply them until the user says yes.

# Rubric (score each 0 or 1)

1. Every quote is found word for word in the file it cites.
2. Every number names its source.
3. The biggest expected finding is first.
4. Single observations are not listed as themes.
5. The disagreement is shown with both sides, not resolved.
6. Nothing appears that is not in the sources.

6 of 6 to ship a skill change. 5 of 6: fix before sharing. Below 5: roll back.

"""Check every quote in a markdown file against the interview it cites.

Usage: python3 evals/check_quotes.py research/synthesis.md
A quote looks like: "some words" (file-name.md)
"""
import os
import re
import sys

ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
DIR = os.path.join(ROOT, "research", "interviews")
QUOTE = re.compile(r'["\u201c]([^"\u201d]{12,}?)["\u201d]\s*\(([^()]+?\.md)\)')


def norm(s):
    s = s.replace("\u2019", "'").replace("\u2018", "'").replace("\u201c", '"').replace("\u201d", '"')
    s = s.replace("\u2026", "...")
    return re.sub(r"\s+", " ", s).strip().lower()


text = open(sys.argv[1], encoding="utf-8").read()
found = QUOTE.findall(text)
missing = []
for quote, name in found:
    path = os.path.join(DIR, os.path.basename(name.strip()))
    body = norm(open(path, encoding="utf-8").read()) if os.path.exists(path) else ""
    parts = [p for p in re.split(r"\.\.\.|\u2026|\[\.\.\.\]", quote) if p.strip()]
    if not body or not all(norm(p) in body for p in parts):
        missing.append((name, quote))

print(f"{len(found)} quotes checked, {len(missing)} missing")
for name, quote in missing:
    print(f"  MISSING in {name}: {quote[:80]}")
sys.exit(1 if missing else 0)