spb/ultra-sharp-agent-skills Public

1<!--2Author: Simon-Pierre Boucher3Contact: contact@spboucher.ai4-->56# Examples — Technical Documentation House Style78## Contents9- Complete worked example: README (bad → house style)10- ADR mini-pattern examples11- Runbook entry (bad → house style)12- Scannability conversions13- Gotchas1415## Complete worked example: README1617**❌ Before (typical drifted README):**1819```markdown20# payment-router2122Welcome to payment-router! This repository contains the source code for the23payment routing system. Payment routing is an important part of our24infrastructure. It is a robust, scalable, high-performance solution.2526## Background2728Historically, payments were processed by the monolith. In 2023 the team29decided to extract routing. There were many discussions about the30architecture. Kafka was considered...3132(three more screens before any command)33```3435**✅ After (house style):**3637```markdown38# payment-router3940Routes card transactions to the cheapest eligible processor. Used by the41checkout service — most engineers only need the client library below.4243## Quickstart4445    pip install payment-router-client4647    from payment_router import route48    decision = route(amount_cents=1999, currency="USD", card_bin="424242")49    print(decision.processor)  # "stripe"5051## How it works5253Each transaction is scored against processor fee tables (refreshed hourly)54and eligibility rules (`rules/*.yaml`). Highest-margin eligible processor55wins. Ties break on historical auth rate.5657## Why SQS, not Kafka5859Context: volume is under 100 msg/s and we already run on AWS.60Decision: SQS for retry queues.61Consequences: no replay; revisit if volume exceeds 1,000 msg/s.6263## Configuration6465| Variable | Default | Effect |66|---|---|---|67| `PR_FEE_REFRESH_MIN` | `60` | Minutes between fee-table refreshes |68| `PR_FALLBACK` | `stripe` | Processor when no rule matches |6970## Operations7172Benchmarks (as of 2026-08): 2,000 req/s on one c7g.large, p99 = 11 ms.73Runbook: [docs/runbook.md](docs/runbook.md)74```7576What changed: purpose + audience in two sentences; runnable quickstart in the77first screen; decision documented with its why; config as a table; verifiable78numbers with a date stamp; zero marketing adjectives.7980## ADR mini-pattern examples8182✅ "Context: we need per-tenant encryption and already use KMS.83Decision: one KMS key per tenant, cached data keys (5 min TTL).84Consequences: +$1/tenant/month; key deletion gives crypto-shredding for free."8586❌ "The system encrypts data per tenant using KMS." (decision with no why —87the next engineer re-litigates it from scratch)8889## Runbook entry (bad → house style)9091**❌ Before:** "If the queue backs up, investigate the consumers and restart92if needed."9394**✅ After:**9596```markdown97## Symptom: `router_queue_depth > 10k` alert98991. Diagnose: `kubectl logs deploy/router-consumer --since=10m | grep ERROR`100   - `FeeTableStale` → refresh job failed, go to step 2101   - `ProcessorTimeout` → upstream incident, escalate to #payments-oncall1022. Fix: `kubectl create job --from=cronjob/fee-refresh manual-refresh`1033. Verify: queue depth falling within 5 minutes.1044. Escalate: if still rising after 15 min, page payments-primary.105```106107## Scannability conversions108109Enumerable prose → table, always:110111❌ "The service supports three modes. In strict mode it rejects unknown112fields. In lenient mode it ignores them. In log mode it accepts them but113logs a warning."114115✅116| Mode | Unknown fields |117|---|---|118| `strict` | rejected (400) |119| `lenient` | ignored |120| `log` | accepted, warning logged |121122## Gotchas123124- **Untested code blocks** are the #1 trust killer — a quickstart that errors125  on line one discredits the whole doc. Run every command before committing.126- **"Simply" and "just"** hide missing steps; delete them and add the step.127- **Architecture docs that describe the aspiration**, not the system as built:128  mark aspirational sections explicitly ("Planned, not implemented").129- **Screenshots** rot fastest of all; prefer text output, and date-stamp any130  screenshot you must include.131- **Duplicated content** between README and wiki always diverges; pick one132  home and link from the other.133