{"id":"code-dev-explain-retry-job-to-pm","audience":"developers","category":"coding","track":"coding","technique":"audience","title":"Explain a background job to your PM without jargon","free":false,"task":"Your PM Dana asks what happens when a receipt email fails. Answer in exactly 3 numbered lines labeled 'What it does:', 'When it fails:' and 'What customers see:', each under 20 words, using what the code actually does (not its outdated docstring). Dana doesn't know engineering terms, so don't use the words cron, API, queue, exception or mailer. No code blocks, under 70 words in total.","materialLabel":"The job's code (attached to your prompt automatically)","material":"# jobs/resend_receipts.py  (Python 3.12, Harborline Tickets)\n# scheduled in crontab:  */15 * * * *  python -m jobs.resend_receipts\n\nfrom billing.models import Receipt\nfrom billing.mail import mailer, MailerError\nfrom support.tickets import notify_support\n\nMAX_ATTEMPTS = 3          # lowered from 5 after the September outage\n\n\ndef run():\n    \"\"\"Resend unsent receipts. Tries each one 5 times, then gives up.\"\"\"\n    for receipt in Receipt.pending():\n        try:\n            mailer.send(receipt.email, receipt.pdf)\n            receipt.mark_sent()\n        except MailerError:\n            receipt.attempts += 1\n            if receipt.attempts >= MAX_ATTEMPTS:\n                receipt.mark_failed()\n                notify_support(receipt)   # opens a ticket in the support inbox\n            receipt.save()\n\n\n# Receipt.pending() = receipts not sent yet and not marked failed.\n# The customer is not emailed about failures; support reaches out\n# from the ticket, usually within one business day.","rules":[{"type":"numberedItems","count":3},{"type":"codeBlocks","count":0},{"type":"maxProseWords","max":70}],"mistakes":[{"title":"Trusting the docstring","why":"The docstring still says 5 tries, but the code stops at 3.","fix":"Add: \"Use what the code does, not the docstring: MAX_ATTEMPTS is 3.\"","checks":["r1"]},{"title":"Engineering words","why":"The AI explains with cron, exceptions and queues, which Dana can't use.","fix":"Add: \"Don't use the words cron, API, queue, exception or mailer.\"","checks":["r2"]},{"title":"A walkthrough of every line","why":"The AI explains the code top to bottom instead of answering Dana's question.","fix":"Say: \"Exactly 3 numbered lines with these labels: What it does:, When it fails:, What customers see:.\"","checks":["r0","numberedItems","maxProseWords"]},{"title":"Showing code","why":"The AI quotes the code back in a block.","fix":"Add: \"No code.\"","checks":["codeBlocks"]}],"promptHints":[{"label":"Says who it's for","patterns":["pm","dana","non-?technical","no jargon"]},{"label":"Gives the labels","patterns":["what it does","when it fails","what customers see"]},{"label":"Bans specific words","patterns":["don'?t use","avoid","no (words|terms)"]},{"label":"Says to trust the code","patterns":["not the (docstring|comment)","max_attempts","\\b3\\b"]},{"label":"Sets the shape","patterns":["\\b(3|three)\\b.{0,15}(line|point)","\\d+\\s*words"]}],"hint":"Dana needs the answer to one question, in her words. Give the AI the labels, the words to avoid, and tell it which part of the code to trust.","rubricLabels":["The three numbered lines start with the labels What it does:, When it fails: and What customers see:, in that order","Says it tries every 15 minutes, up to 3 times (not 5), and then opens a support ticket, and that customers aren't told automatically but support reaches out (within about a business day)","Doesn't use any of the words cron, API, queue, exception or mailer"]}