Module 12. Capstone engagement and positioning

Lab 12. Plan, case study generator, go-to-market tracker

Goal: three working tools you will use for the next 90 days. Everything runs locally; only the case study script calls the API, and it has a dry-run mode that does not.

Part 1 (about 2 h). Engagement plan and ADR for your chosen client

1. Score your three candidates against the four tests in 12.1. Choose one and write two lines on why.
2. Copy the table from 12.2 into a document and fill in real dates, the named owner contact and the primary metric.
3. Copy the ADR template above into adr/ADR-001.md and fill it in after the audit. Include "do nothing" and "Claude app with a Project" as options.
4. Write the one-page scope with the owner: goal, metric, data, who approves, what may be published.

Part 2 (about 2 h). Case study draft generator

Setup (same repository as the earlier labs):

cd claude-transformation
source .venv/bin/activate
pip install anthropic python-dotenv
mkdir module12 && cd module12

engagement.json (all values are placeholders; fill them from your real logs)

{
  "client_label": "A small logistics company in central Israel",
  "client_name": "[client name]",
  "client_name_approved": false,
  "sector": "logistics",
  "problem": "[What was slow or error-prone, in the owner's words. Facts only.]",
  "approach": "[Audit, architecture decision, two-week pilot. Add real dates.]",
  "solution": "[What was built: model, tools, the human review step.]",
  "metrics": [
    {
      "name": "Median time to first reply to a shipment-status email",
      "unit": "minutes",
      "better_when": "lower",
      "baseline": null,
      "after": null,
      "n_baseline": null,
      "n_after": null,
      "period": "[baseline dates] vs [pilot dates]",
      "method": "[how it was measured, by whom]"
    },
    {
      "name": "Status emails handled per clerk per day",
      "unit": "emails",
      "better_when": "higher",
      "baseline": null,
      "after": null,
      "n_baseline": null,
      "n_after": null,
      "period": "[baseline dates] vs [pilot dates]",
      "method": "[how it was measured, by whom]"
    }
  ],
  "caveats": [
    "[confirm] One company, one pilot, short period.",
    "[confirm] No control group; other changes in the period are possible.",
    "[confirm] Time figures come from the mail log, not from self-reports."
  ],
  "quote": {
    "text": null,
    "speaker": null,
    "role": null,
    "approved": false,
    "approval_date": null
  }
}

case_study.py

#!/usr/bin/env python3
"""case_study.py - turn engagement.json into draft case studies (English + Hebrew).

The output is a DRAFT for you to edit. Facts come only from the JSON.
Percent changes are computed here in Python, not by the model.

Usage:
    python case_study.py engagement.json --dry-run --allow-missing   # no API call
    python case_study.py engagement.json --out drafts                # real run
"""
import argparse
import copy
import json
import sys
from pathlib import Path

MODEL = "claude-sonnet-5-5"  # check current IDs at docs.claude.com

REQUIRED_TOP = ["client_label", "problem", "approach", "solution", "metrics", "caveats"]
REQUIRED_METRIC = ["name", "unit", "baseline", "after", "n_baseline", "n_after", "period"]

SYSTEM = """You draft case studies for a small IT consultancy.
Rules:
- Use only facts and numbers that appear in the JSON. Never invent numbers, names, dates or quotes.
- If a value is null, empty or a [bracketed placeholder], keep it visible as [MISSING: field name].
- Use change_pct exactly as given. Do not recalculate. If it is null, say the change cannot be stated yet.
- Next to every result, state the sample sizes (n_baseline, n_after) and the period.
- If quote.approved is not true, write [QUOTE PENDING APPROVAL] and no quote text.
- If client_name is absent, use client_label. Do not guess the client's identity.
- Include every caveat from the JSON in a Caveats section.
- Plain, direct language. No hype, no superlatives.
- Sections, in order: Problem, Approach, Solution, Results, Caveats, Quote.
- Output Markdown only."""

LANG_NOTES = {
    "en": "Write in English.",
    "he": (
        "Write in natural business Hebrew, not a literal translation. "
        "Translate the section headings into Hebrew. Keep numbers, units and "
        "product names (Claude, MCP, Python) in Latin characters."
    ),
}


def pct_change(baseline, after):
    """Percent change from baseline to after, or None if it cannot be computed."""
    nums = (int, float)
    if not isinstance(baseline, nums) or not isinstance(after, nums) or baseline == 0:
        return None
    return round((after - baseline) / baseline * 100, 1)


def find_missing(data):
    """Return a list of required fields that are empty."""
    missing = []
    for key in REQUIRED_TOP:
        if data.get(key) in (None, "", []):
            missing.append(key)
    for i, metric in enumerate(data.get("metrics") or []):
        for key in REQUIRED_METRIC:
            if metric.get(key) is None:
                missing.append(f"metrics[{i}].{key}")
    return missing


def prepare(data):
    """Copy the data, add computed changes, strip anything not approved."""
    d = copy.deepcopy(data)
    for metric in d.get("metrics", []):
        metric["change_pct"] = pct_change(metric.get("baseline"), metric.get("after"))
    quote = d.get("quote") or {}
    if quote.get("approved") is not True:
        d["quote"] = {"approved": False}  # quote text never reaches the model
    if d.get("client_name_approved") is not True:
        d.pop("client_name", None)
    return d


def build_prompt(prepared, lang):
    return (
        f"{LANG_NOTES[lang]}\n\n"
        "Draft the case study from this engagement data:\n\n"
        + json.dumps(prepared, ensure_ascii=False, indent=2)
    )


def draft(client, prepared, lang):
    msg = client.messages.create(
        model=MODEL,
        max_tokens=2000,
        system=SYSTEM,
        messages=[{"role": "user", "content": build_prompt(prepared, lang)}],
    )
    return "".join(b.text for b in msg.content if b.type == "text")


def main():
    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    ap.add_argument("path", help="engagement JSON file")
    ap.add_argument("--langs", default="en,he", help="comma list: en,he")
    ap.add_argument("--out", default=".", help="output folder")
    ap.add_argument("--dry-run", action="store_true", help="print prompts, no API call")
    ap.add_argument("--allow-missing", action="store_true", help="continue with gaps")
    args = ap.parse_args()

    data = json.loads(Path(args.path).read_text(encoding="utf-8"))
    missing = find_missing(data)
    if missing:
        print("Missing fields:", ", ".join(missing), file=sys.stderr)
        if not args.allow_missing:
            print("Fill them in, or pass --allow-missing for a gap-marked draft.", file=sys.stderr)
            return 2

    prepared = prepare(data)
    langs = [x.strip() for x in args.langs.split(",") if x.strip()]
    bad = [x for x in langs if x not in LANG_NOTES]
    if bad:
        print("Unsupported language:", ", ".join(bad), file=sys.stderr)
        return 2

    if args.dry_run:
        for lang in langs:
            print(f"--- PROMPT ({lang}) ---")
            print(build_prompt(prepared, lang))
        return 0

    import anthropic  # imported here so --dry-run works without the package
    from dotenv import load_dotenv

    load_dotenv()
    client = anthropic.Anthropic()
    out_dir = Path(args.out)
    out_dir.mkdir(parents=True, exist_ok=True)
    for lang in langs:
        text = draft(client, prepared, lang)
        header = (
            "<!-- DRAFT for Oleg to edit. Not approved by the client. "
            "Check every number against the source data. -->\n\n"
        )
        target = out_dir / f"case_study_{lang}.md"
        target.write_text(header + text + "\n", encoding="utf-8")
        print("Wrote", target)
    return 0


if __name__ == "__main__":
    sys.exit(main())

Run it:

python case_study.py engagement.json --dry-run --allow-missing   # see the prompts, no API call
python case_study.py engagement.json                             # stops and lists missing fields
python case_study.py engagement.json --out drafts                # after you fill in real data

What to notice: the percent change is calculated in Python, the quote text never reaches the model unless approved is true, and missing values stay visible as [MISSING: ...]. Edit both drafts by hand. The model's Hebrew is a first draft; your version is the one you publish.

Part 3 (about 2 h). 90-day go-to-market tracker

gtm_tracker.csv (sample rows with placeholder names; replace them with your 30 companies)

company,segment,source,contact_role,stage,status,first_contact,last_contact,next_action,next_action_date,notes
[Company 01],logistics,warm_intro,owner,contacted,open,2026-10-19,2026-10-19,follow-up message,2026-10-23,[who introduced]
[Company 02],logistics,linkedin,operations manager,replied,open,2026-10-19,2026-10-21,book 20-min call,2026-10-26,
[Company 03],services,cold,owner,target,open,,,first message,2026-10-22,
[Company 04],garage,warm_intro,owner,call_held,open,2026-10-12,2026-10-20,send audit scope,2026-10-27,[friendly capstone candidate]
[Company 05],ceramics,warm_intro,owner,contacted,lost,2026-10-12,2026-10-14,,,[reason in one line]

gtm_summary.py

#!/usr/bin/env python3
"""gtm_summary.py - weekly summary of a 90-day go-to-market tracker CSV.

Usage:
    python gtm_summary.py gtm_tracker.csv
    python gtm_summary.py gtm_tracker.csv --today 2026-10-26
Weeks run Sunday to Saturday (Israeli work week).
"""
import argparse
import csv
import sys
from collections import Counter
from datetime import date, datetime, timedelta
from pathlib import Path

STAGES = [
    "target",
    "contacted",
    "replied",
    "call_held",
    "audit_proposed",
    "audit_won",
    "pilot_won",
    "retainer_won",
]
STATUSES = {"open", "lost", "paused"}
STALE_DAYS = 21


def parse_date(text, row_no, column):
    text = (text or "").strip()
    if not text:
        return None
    try:
        return datetime.strptime(text, "%Y-%m-%d").date()
    except ValueError:
        raise SystemExit(f"Row {row_no}: {column} '{text}' is not YYYY-MM-DD")


def load(path):
    rows = []
    with open(path, newline="", encoding="utf-8") as f:
        for n, row in enumerate(csv.DictReader(f), start=2):  # row 1 is the header
            stage = (row.get("stage") or "").strip()
            status = (row.get("status") or "open").strip()
            if stage not in STAGES:
                raise SystemExit(f"Row {n}: unknown stage '{stage}'. Use one of: {', '.join(STAGES)}")
            if status not in STATUSES:
                raise SystemExit(f"Row {n}: unknown status '{status}'. Use one of: {', '.join(sorted(STATUSES))}")
            row["stage"], row["status"] = stage, status
            for col in ("first_contact", "last_contact", "next_action_date"):
                row[col] = parse_date(row.get(col), n, col)
            rows.append(row)
    return rows


def week_start(day):
    """Sunday of the week containing `day`."""
    return day - timedelta(days=(day.weekday() + 1) % 7)


def reached(row, stage):
    return STAGES.index(row["stage"]) >= STAGES.index(stage)


def rate(part, whole):
    return f"{part / whole * 100:.0f}%" if whole else "n/a"


def summarise(rows, today):
    start = week_start(today)
    end = start + timedelta(days=6)
    out = []
    out.append(f"GTM summary for week {start} to {end} (today {today})")
    out.append(f"Rows: {len(rows)}  open: {sum(r['status'] == 'open' for r in rows)}")

    out.append("\nFunnel (companies that reached each stage)")
    previous = None
    for stage in STAGES:
        count = sum(reached(r, stage) for r in rows)
        step = f"  ({rate(count, previous)} of previous)" if previous is not None else ""
        out.append(f"  {stage:<15}{count:>4}{step}")
        previous = count

    new_this_week = [r for r in rows if r["first_contact"] and start <= r["first_contact"] <= end]
    touched = [r for r in rows if r["last_contact"] and start <= r["last_contact"] <= end]
    out.append("\nThis week")
    out.append(f"  new first contacts: {len(new_this_week)}")
    out.append(f"  companies touched:  {len(touched)}")

    out.append("\nReply rate by source (replied or further / contacted or further)")
    contacted_by, replied_by = Counter(), Counter()
    for r in rows:
        if reached(r, "contacted"):
            contacted_by[r["source"]] += 1
            if reached(r, "replied"):
                replied_by[r["source"]] += 1
    for source in sorted(contacted_by):
        c, p = contacted_by[source], replied_by[source]
        out.append(f"  {source:<12}{p}/{c}  {rate(p, c)}")
    if not contacted_by:
        out.append("  no contacts yet")

    open_rows = [r for r in rows if r["status"] == "open"]
    due = sorted(
        (r for r in open_rows if r["next_action_date"] and r["next_action_date"] <= end),
        key=lambda r: r["next_action_date"],
    )
    out.append("\nActions due by end of this week")
    for r in due:
        flag = "OVERDUE " if r["next_action_date"] < today else ""
        out.append(f"  {r['next_action_date']}  {flag}{r['company']}: {r['next_action']}")
    if not due:
        out.append("  none")

    stale = [
        r for r in open_rows
        if r["stage"] == "contacted" and r["last_contact"]
        and (today - r["last_contact"]).days > STALE_DAYS
    ]
    out.append(f"\nStale: contacted, no reply, last touch over {STALE_DAYS} days ago")
    for r in stale:
        out.append(f"  {r['company']} (last touch {r['last_contact']}): pause or close")
    if not stale:
        out.append("  none")

    no_action = [r for r in open_rows if not r["next_action_date"] and r["stage"] != "retainer_won"]
    out.append("\nOpen rows with no next action date")
    for r in no_action:
        out.append(f"  {r['company']}")
    if not no_action:
        out.append("  none")
    return "\n".join(out)


def main():
    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    ap.add_argument("csv_path")
    ap.add_argument("--today", help="override today, YYYY-MM-DD")
    args = ap.parse_args()
    if not Path(args.csv_path).exists():
        print(f"File not found: {args.csv_path}", file=sys.stderr)
        return 2
    today = datetime.strptime(args.today, "%Y-%m-%d").date() if args.today else date.today()
    print(summarise(load(args.csv_path), today))
    return 0


if __name__ == "__main__":
    sys.exit(main())

Run it every Sunday morning:

python gtm_summary.py gtm_tracker.csv
python gtm_summary.py gtm_tracker.csv --today 2026-10-22   # test with a chosen date

1. Replace the sample rows with your 30 targets (stage target, a first action and date for each).
2. Update the CSV after every contact. Stages are in order: target, contacted, replied, call_held, audit_proposed, audit_won, pilot_won, retainer_won. A lost or paused company keeps its furthest stage and gets a different status.
3. After four weeks, read the reply rate by source and decide where to put your time.