spb/ultra-sharp-agent-skills Public

1<!--2Author: Simon-Pierre Boucher3Contact: contact@spboucher.ai4-->56# Examples — Tutorial House Style78## Contents9- Complete worked example: tutorial opening + one step (bad → house style)10- Checkpoint patterns11- Inline troubleshooting pattern12- Ending pattern13- Gotchas1415## Complete worked example1617**❌ Before:**1819```markdown20# Webhooks tutorial2122In this tutorial we will learn about webhooks. Webhooks are a way for23services to notify each other. First, set up your environment and create24a project. You can use Flask, FastAPI, or Django. Then write a handler25for the webhook and test it works.26```2728**✅ After (house style):**2930```markdown31# Receive Stripe webhooks locally3233By the end you'll have a local endpoint that verifies and logs Stripe34events, reachable from the internet.3536**Prerequisites:** Python 3.12, a free Stripe test account, ngrok 3.x37installed. **Time:** ~20 minutes.3839## Step 1 — Create the project4041    mkdir stripe-webhooks && cd stripe-webhooks42    python3 -m venv .venv43    source .venv/bin/activate44    pip install fastapi==0.115.0 uvicorn==0.30.0 stripe==10.5.04546Expected output ends with:4748    Successfully installed fastapi-0.115.0 stripe-10.5.0 uvicorn-0.30.04950**Checkpoint:** `python -c "import fastapi, stripe; print('ok')"` prints `ok`.5152> If you see `command not found: python3`, install Python 3.12 from53> python.org, then restart this step in a new terminal.54```5556What changed: destination + prerequisites + time before step 1; one framework57(no menu); full commands including venv activation; pinned versions; expected58output; a checkpoint; the likeliest failure handled inline.5960## Checkpoint patterns6162✅ Observable and exact:63- "You should see `{"status":"ok"}`."64- "The dashboard now lists one endpoint with a green Active badge."65- "`ls migrations/` shows one file ending in `_init.py`."6667❌ Unverifiable:68- "Make sure everything is configured correctly."69- "The server should now be working."7071## Inline troubleshooting pattern7273Place at the step, as a quote block, most-likely first:7475```markdown76> **`Address already in use`** — another process holds port 8000:77> `lsof -i :8000`, stop it, rerun.78> **`401 Unauthorized` from Stripe** — you exported the live key;79> re-export the one starting with `sk_test_`.80```8182Cap at 3 per step; more than that means the step itself needs splitting.8384## Ending pattern8586```markdown87## What you built8889A verified Stripe webhook receiver: signature checking, event logging,90and a public URL via ngrok.9192## Where to go next9394- Handle `invoice.paid` and update your database — see Persisting events95- Deploy the receiver — see Deploying FastAPI96- Full event catalog: Stripe docs, Webhook events97```9899## Gotchas100101- **The author's environment leaks in** (aliases, globally installed tools,102  exported variables from earlier work). Only a clean-environment replay103  catches these — do it, every time.104- **Unpinned versions** make tutorials rot silently; pin every install and105  date-stamp the tested versions.106- **"Simply", "just", "obviously"** mark exactly the places learners get107  stuck; delete the word, add the missing step.108- **Screenshots of terminals** can't be copy-pasted or diffed; use text109  blocks for anything the learner must compare.110- **Checkpoint drift:** when you edit a step, its expected output usually111  changes too — replay from the edited step onward, not just the step.112