[{"data":1,"prerenderedAt":2226},["ShallowReactive",2],{"page-\u002Fprompt-engineering\u002F04-clarity-and-specificity":3},{"id":4,"title":5,"body":6,"description":2219,"extension":2220,"meta":2221,"navigation":61,"path":2222,"seo":2223,"stem":2224,"__hash__":2225},"content\u002Fprompt-engineering\u002F04-clarity-and-specificity.md","04 — Clarity & Specificity",{"type":7,"value":8,"toc":2208},"minimark",[9,13,18,27,307,311,325,427,430,434,457,490,1447,1451,1474,1502,1689,1693,1736,1740,1864,1868,2017,2021,2044,2047,2064,2068,2204],[10,11,5],"h1",{"id":12},"_04-clarity-specificity",[14,15,17],"h2",{"id":16},"ambiguity-is-the-default-eliminate-it-explicitly","Ambiguity Is the Default — Eliminate It Explicitly",[19,20,21,22,26],"p",{},"Every sentence has a space of plausible interpretations. The model picks one — silently. Vague prompts don't fail because the model is dumb; they fail because you under-specified the problem and the model faithfully answered a ",[23,24,25],"em",{},"different, equally valid"," reading.",[28,29,32],"code-wrapper",{"filename":30,"language":31},"ambiguity_axes.py","python",[33,34,38],"pre",{"className":35,"code":36,"language":31,"meta":37,"style":37},"language-python shiki shiki-themes github-light github-dark","# The core discipline: identify EVERY axis of ambiguity and decide explicitly.\n# \"Summarize this article\" — the model must silently decide:\n\nAMBIGUITY_AXES = {\n    \"audience\":       None,  # for whom? exec? engineer? customer?\n    \"length\":         None,  # 1 sentence? 3 paragraphs? 500 words?\n    \"preserve\":       None,  # key facts? author's argument? action items?\n    \"tone\":           None,  # formal? casual? technical?\n    \"format\":         None,  # plain text? bullets? table? markdown?\n    \"emphasis\":       None,  # what to highlight? what to omit?\n}\n\n# The model WILL pick a value for each. You either specify it or accept its guess.\n# Production approach: treat each None as a bug.\n\nSPECIFIED = {\n    \"audience\":       \"engineering team lead who needs the actionable points\",\n    \"length\":         \"exactly 3 bullet points, max 20 words each\",\n    \"preserve\":       \"only decisions and their rationale, not background\",\n    \"tone\":           \"terse, declarative, no hedging language\",\n    \"format\":         \"markdown bullet list, no preamble, no closing remarks\",\n    \"emphasis\":       \"highlight anything blocking or at-risk; omit process details\",\n}\n\n# Every value here is CHECKABLE — you or an eval can verify pass\u002Ffail.\n# \"concise\" is not checkable. \"max 20 words per bullet\" is.\n","",[39,40,41,50,56,63,78,97,113,128,144,159,174,180,185,191,197,202,212,225,237,249,261,273,285,290,295,301],"code",{"__ignoreMap":37},[42,43,46],"span",{"class":44,"line":45},"line",1,[42,47,49],{"class":48},"sdCPZ","# The core discipline: identify EVERY axis of ambiguity and decide explicitly.\n",[42,51,53],{"class":44,"line":52},2,[42,54,55],{"class":48},"# \"Summarize this article\" — the model must silently decide:\n",[42,57,59],{"class":44,"line":58},3,[42,60,62],{"emptyLinePlaceholder":61},true,"\n",[42,64,66,70,74],{"class":44,"line":65},4,[42,67,69],{"class":68},"snvgF","AMBIGUITY_AXES",[42,71,73],{"class":72},"svdQ7"," =",[42,75,77],{"class":76},"ssxIu"," {\n",[42,79,81,85,88,91,94],{"class":44,"line":80},5,[42,82,84],{"class":83},"sJ6F3","    \"audience\"",[42,86,87],{"class":76},":       ",[42,89,90],{"class":68},"None",[42,92,93],{"class":76},",  ",[42,95,96],{"class":48},"# for whom? exec? engineer? customer?\n",[42,98,100,103,106,108,110],{"class":44,"line":99},6,[42,101,102],{"class":83},"    \"length\"",[42,104,105],{"class":76},":         ",[42,107,90],{"class":68},[42,109,93],{"class":76},[42,111,112],{"class":48},"# 1 sentence? 3 paragraphs? 500 words?\n",[42,114,116,119,121,123,125],{"class":44,"line":115},7,[42,117,118],{"class":83},"    \"preserve\"",[42,120,87],{"class":76},[42,122,90],{"class":68},[42,124,93],{"class":76},[42,126,127],{"class":48},"# key facts? author's argument? action items?\n",[42,129,131,134,137,139,141],{"class":44,"line":130},8,[42,132,133],{"class":83},"    \"tone\"",[42,135,136],{"class":76},":           ",[42,138,90],{"class":68},[42,140,93],{"class":76},[42,142,143],{"class":48},"# formal? casual? technical?\n",[42,145,147,150,152,154,156],{"class":44,"line":146},9,[42,148,149],{"class":83},"    \"format\"",[42,151,105],{"class":76},[42,153,90],{"class":68},[42,155,93],{"class":76},[42,157,158],{"class":48},"# plain text? bullets? table? markdown?\n",[42,160,162,165,167,169,171],{"class":44,"line":161},10,[42,163,164],{"class":83},"    \"emphasis\"",[42,166,87],{"class":76},[42,168,90],{"class":68},[42,170,93],{"class":76},[42,172,173],{"class":48},"# what to highlight? what to omit?\n",[42,175,177],{"class":44,"line":176},11,[42,178,179],{"class":76},"}\n",[42,181,183],{"class":44,"line":182},12,[42,184,62],{"emptyLinePlaceholder":61},[42,186,188],{"class":44,"line":187},13,[42,189,190],{"class":48},"# The model WILL pick a value for each. You either specify it or accept its guess.\n",[42,192,194],{"class":44,"line":193},14,[42,195,196],{"class":48},"# Production approach: treat each None as a bug.\n",[42,198,200],{"class":44,"line":199},15,[42,201,62],{"emptyLinePlaceholder":61},[42,203,205,208,210],{"class":44,"line":204},16,[42,206,207],{"class":68},"SPECIFIED",[42,209,73],{"class":72},[42,211,77],{"class":76},[42,213,215,217,219,222],{"class":44,"line":214},17,[42,216,84],{"class":83},[42,218,87],{"class":76},[42,220,221],{"class":83},"\"engineering team lead who needs the actionable points\"",[42,223,224],{"class":76},",\n",[42,226,228,230,232,235],{"class":44,"line":227},18,[42,229,102],{"class":83},[42,231,105],{"class":76},[42,233,234],{"class":83},"\"exactly 3 bullet points, max 20 words each\"",[42,236,224],{"class":76},[42,238,240,242,244,247],{"class":44,"line":239},19,[42,241,118],{"class":83},[42,243,87],{"class":76},[42,245,246],{"class":83},"\"only decisions and their rationale, not background\"",[42,248,224],{"class":76},[42,250,252,254,256,259],{"class":44,"line":251},20,[42,253,133],{"class":83},[42,255,136],{"class":76},[42,257,258],{"class":83},"\"terse, declarative, no hedging language\"",[42,260,224],{"class":76},[42,262,264,266,268,271],{"class":44,"line":263},21,[42,265,149],{"class":83},[42,267,105],{"class":76},[42,269,270],{"class":83},"\"markdown bullet list, no preamble, no closing remarks\"",[42,272,224],{"class":76},[42,274,276,278,280,283],{"class":44,"line":275},22,[42,277,164],{"class":83},[42,279,87],{"class":76},[42,281,282],{"class":83},"\"highlight anything blocking or at-risk; omit process details\"",[42,284,224],{"class":76},[42,286,288],{"class":44,"line":287},23,[42,289,179],{"class":76},[42,291,293],{"class":44,"line":292},24,[42,294,62],{"emptyLinePlaceholder":61},[42,296,298],{"class":44,"line":297},25,[42,299,300],{"class":48},"# Every value here is CHECKABLE — you or an eval can verify pass\u002Ffail.\n",[42,302,304],{"class":44,"line":303},26,[42,305,306],{"class":48},"# \"concise\" is not checkable. \"max 20 words per bullet\" is.\n",[14,308,310],{"id":309},"complex-implementation-vague-vs-specified","Complex Implementation: Vague vs. Specified",[28,312,315],{"filename":313,"language":314},"vague_prompt.md","markdown",[33,316,319],{"className":317,"code":318,"language":314,"meta":37,"style":37},"language-markdown shiki shiki-themes github-light github-dark","Write a product description for our new wireless earbuds.\n",[39,320,321],{"__ignoreMap":37},[42,322,323],{"class":44,"line":45},[42,324,318],{"class":76},[28,326,328],{"filename":327,"language":314},"specified_prompt.md",[33,329,331],{"className":317,"code":330,"language":314,"meta":37,"style":37},"Write a product description for our new wireless earbuds, the \"Aria Pro.\"\n\nAudience: existing customers on our e-commerce product page, most of whom\nalready own one of our older audio products and are comparison-shopping\nagainst the previous generation.\n\nLength: exactly 3 short paragraphs, no more than 60 words each.\n\nTone: confident and specific, not hype-driven. Avoid superlatives like\n\"revolutionary\" or \"game-changing.\" We're a brand known for understated,\nengineer-focused copy.\n\nMust mention: 30-hour battery life with the case, active noise cancellation\n(new in this model, the previous generation didn't have it), and IPX4\nwater resistance.\n\nDo not mention: price (set elsewhere on the page) or compare directly to\nnamed competitor products.\n\nFormat: no title\u002Fheading, just the three paragraphs, no bullet points.\n",[39,332,333,338,342,347,352,357,361,366,370,375,380,385,389,394,399,404,408,413,418,422],{"__ignoreMap":37},[42,334,335],{"class":44,"line":45},[42,336,337],{"class":76},"Write a product description for our new wireless earbuds, the \"Aria Pro.\"\n",[42,339,340],{"class":44,"line":52},[42,341,62],{"emptyLinePlaceholder":61},[42,343,344],{"class":44,"line":58},[42,345,346],{"class":76},"Audience: existing customers on our e-commerce product page, most of whom\n",[42,348,349],{"class":44,"line":65},[42,350,351],{"class":76},"already own one of our older audio products and are comparison-shopping\n",[42,353,354],{"class":44,"line":80},[42,355,356],{"class":76},"against the previous generation.\n",[42,358,359],{"class":44,"line":99},[42,360,62],{"emptyLinePlaceholder":61},[42,362,363],{"class":44,"line":115},[42,364,365],{"class":76},"Length: exactly 3 short paragraphs, no more than 60 words each.\n",[42,367,368],{"class":44,"line":130},[42,369,62],{"emptyLinePlaceholder":61},[42,371,372],{"class":44,"line":146},[42,373,374],{"class":76},"Tone: confident and specific, not hype-driven. Avoid superlatives like\n",[42,376,377],{"class":44,"line":161},[42,378,379],{"class":76},"\"revolutionary\" or \"game-changing.\" We're a brand known for understated,\n",[42,381,382],{"class":44,"line":176},[42,383,384],{"class":76},"engineer-focused copy.\n",[42,386,387],{"class":44,"line":182},[42,388,62],{"emptyLinePlaceholder":61},[42,390,391],{"class":44,"line":187},[42,392,393],{"class":76},"Must mention: 30-hour battery life with the case, active noise cancellation\n",[42,395,396],{"class":44,"line":193},[42,397,398],{"class":76},"(new in this model, the previous generation didn't have it), and IPX4\n",[42,400,401],{"class":44,"line":199},[42,402,403],{"class":76},"water resistance.\n",[42,405,406],{"class":44,"line":204},[42,407,62],{"emptyLinePlaceholder":61},[42,409,410],{"class":44,"line":214},[42,411,412],{"class":76},"Do not mention: price (set elsewhere on the page) or compare directly to\n",[42,414,415],{"class":44,"line":227},[42,416,417],{"class":76},"named competitor products.\n",[42,419,420],{"class":44,"line":239},[42,421,62],{"emptyLinePlaceholder":61},[42,423,424],{"class":44,"line":251},[42,425,426],{"class":76},"Format: no title\u002Fheading, just the three paragraphs, no bullet points.\n",[19,428,429],{},"Every added clause removed one axis of ambiguity. The output from the second prompt is dramatically more likely to be usable without editing — not because the model \"tried harder,\" but because there's almost nothing left to guess.",[14,431,433],{"id":432},"anti-pattern-vague-constraints","Anti-Pattern: Vague Constraints",[28,435,437],{"filename":436,"language":314},"anti_pattern_vague.md",[33,438,440],{"className":317,"code":439,"language":314,"meta":37,"style":37},"\u003C!-- ANTI-PATTERN: none of these constraints are checkable -->\nExplain what a foreign key is, but keep it short and simple, for someone\nwho isn't very technical.\n",[39,441,442,447,452],{"__ignoreMap":37},[42,443,444],{"class":44,"line":45},[42,445,446],{"class":48},"\u003C!-- ANTI-PATTERN: none of these constraints are checkable -->\n",[42,448,449],{"class":44,"line":52},[42,450,451],{"class":76},"Explain what a foreign key is, but keep it short and simple, for someone\n",[42,453,454],{"class":44,"line":58},[42,455,456],{"class":76},"who isn't very technical.\n",[28,458,460],{"filename":459,"language":314},"production_specified.md",[33,461,463],{"className":317,"code":462,"language":314,"meta":37,"style":37},"\u003C!-- PRODUCTION: every constraint is independently verifiable -->\nExplain what a foreign key is in exactly 2 sentences. Assume the reader\nhas never written SQL but understands what a spreadsheet is — use a\nspreadsheet analogy if it helps. Do not use the words \"constraint,\"\n\"integrity,\" or \"schema.\"\n",[39,464,465,470,475,480,485],{"__ignoreMap":37},[42,466,467],{"class":44,"line":45},[42,468,469],{"class":48},"\u003C!-- PRODUCTION: every constraint is independently verifiable -->\n",[42,471,472],{"class":44,"line":52},[42,473,474],{"class":76},"Explain what a foreign key is in exactly 2 sentences. Assume the reader\n",[42,476,477],{"class":44,"line":58},[42,478,479],{"class":76},"has never written SQL but understands what a spreadsheet is — use a\n",[42,481,482],{"class":44,"line":65},[42,483,484],{"class":76},"spreadsheet analogy if it helps. Do not use the words \"constraint,\"\n",[42,486,487],{"class":44,"line":80},[42,488,489],{"class":76},"\"integrity,\" or \"schema.\"\n",[28,491,493],{"filename":492,"language":31},"constraint_validator.py",[33,494,496],{"className":35,"code":495,"language":31,"meta":37,"style":37},"import re\n\nclass PromptConstraintValidator:\n    \"\"\"Validates that prompt constraints are checkable, not vibes.\n    Use during prompt development to catch vague language before it ships.\"\"\"\n\n    VAGUE_TERMS = {\n        \"concise\", \"brief\", \"short\", \"simple\", \"detailed\", \"thorough\",\n        \"appropriate\", \"nice\", \"good\", \"professional\", \"casual\",\n        \"several\", \"a few\", \"some\", \"various\", \"relevant\",\n    }\n\n    def __init__(self, prompt_text: str):\n        self.prompt = prompt_text\n        self.violations: list[str] = []\n\n    def check_vague_terms(self) -> list[str]:\n        \"\"\"Flag vague adjectives that have no fixed meaning.\"\"\"\n        words = re.findall(r'\\b[a-z]+\\b', self.prompt.lower())\n        found = [w for w in words if w in self.VAGUE_TERMS]\n        if found:\n            self.violations.append(\n                f\"Vague terms found: {found}. Replace with quantifiable \"\n                f\"constraints ('exactly 3 sentences', not 'keep it short').\"\n            )\n        return found\n\n    def check_quantifiable(self) -> bool:\n        \"\"\"Verify at least one numeric\u002Fstructural constraint exists.\"\"\"\n        has_number = bool(re.search(r'\\b\\d+\\b', self.prompt))\n        has_structure = any(\n            term in self.prompt.lower()\n            for term in [\"json\", \"table\", \"bullet\", \"list\", \"exactly\", \"at most\", \"no more than\"]\n        )\n        if not (has_number or has_structure):\n            self.violations.append(\n                \"No quantifiable constraint found. Add specific counts, \"\n                \"lengths, or format requirements.\"\n            )\n        return has_number or has_structure\n\n    def check_negative_framing(self) -> list[str]:\n        \"\"\"Flag broad negative instructions prone to ironic rebound.\"\"\"\n        broad_negatives = re.findall(\n            r\"don't (?:be|sound|include|mention|use) (\\w+)\", self.prompt.lower()\n        )\n        conceptual = {\"scary\", \"biased\", \"robotic\", \"formal\", \"casual\", \"technical\"}\n        risky = [n for n in broad_negatives if n in conceptual]\n        if risky:\n            self.violations.append(\n                f\"Broad negative instructions for conceptual categories: {risky}. \"\n                f\"Name the concept → activates it (ironic rebound). \"\n                f\"Reframe as positive: describe the DESIRED behavior instead.\"\n            )\n        return risky\n\n    def validate(self) -> bool:\n        self.check_vague_terms()\n        self.check_quantifiable()\n        self.check_negative_framing()\n        if self.violations:\n            for v in self.violations:\n                print(f\"  ⚠️  {v}\")\n            return False\n        return True\n\n# Usage:\nvalidator = PromptConstraintValidator(\"\"\"\nExplain what a foreign key is in exactly 2 sentences. Do not be scary\nor use jargon. Keep it simple.\n\"\"\")\nvalidator.validate()\n# ⚠️ Vague terms found: ['simple']\n# ⚠️ Broad negative instructions for conceptual categories: ['scary']\n",[39,497,498,506,510,522,527,532,536,545,578,605,632,637,641,658,672,689,693,708,713,748,789,797,805,825,832,837,845,850,866,872,906,920,933,982,988,1005,1012,1018,1024,1029,1042,1047,1061,1067,1078,1136,1141,1181,1211,1219,1226,1244,1252,1260,1265,1273,1278,1292,1300,1308,1316,1326,1340,1367,1376,1384,1389,1395,1409,1415,1421,1429,1435,1441],{"__ignoreMap":37},[42,499,500,503],{"class":44,"line":45},[42,501,502],{"class":72},"import",[42,504,505],{"class":76}," re\n",[42,507,508],{"class":44,"line":52},[42,509,62],{"emptyLinePlaceholder":61},[42,511,512,515,519],{"class":44,"line":58},[42,513,514],{"class":72},"class",[42,516,518],{"class":517},"sIsaT"," PromptConstraintValidator",[42,520,521],{"class":76},":\n",[42,523,524],{"class":44,"line":65},[42,525,526],{"class":83},"    \"\"\"Validates that prompt constraints are checkable, not vibes.\n",[42,528,529],{"class":44,"line":80},[42,530,531],{"class":83},"    Use during prompt development to catch vague language before it ships.\"\"\"\n",[42,533,534],{"class":44,"line":99},[42,535,62],{"emptyLinePlaceholder":61},[42,537,538,541,543],{"class":44,"line":115},[42,539,540],{"class":68},"    VAGUE_TERMS",[42,542,73],{"class":72},[42,544,77],{"class":76},[42,546,547,550,553,556,558,561,563,566,568,571,573,576],{"class":44,"line":130},[42,548,549],{"class":83},"        \"concise\"",[42,551,552],{"class":76},", ",[42,554,555],{"class":83},"\"brief\"",[42,557,552],{"class":76},[42,559,560],{"class":83},"\"short\"",[42,562,552],{"class":76},[42,564,565],{"class":83},"\"simple\"",[42,567,552],{"class":76},[42,569,570],{"class":83},"\"detailed\"",[42,572,552],{"class":76},[42,574,575],{"class":83},"\"thorough\"",[42,577,224],{"class":76},[42,579,580,583,585,588,590,593,595,598,600,603],{"class":44,"line":146},[42,581,582],{"class":83},"        \"appropriate\"",[42,584,552],{"class":76},[42,586,587],{"class":83},"\"nice\"",[42,589,552],{"class":76},[42,591,592],{"class":83},"\"good\"",[42,594,552],{"class":76},[42,596,597],{"class":83},"\"professional\"",[42,599,552],{"class":76},[42,601,602],{"class":83},"\"casual\"",[42,604,224],{"class":76},[42,606,607,610,612,615,617,620,622,625,627,630],{"class":44,"line":161},[42,608,609],{"class":83},"        \"several\"",[42,611,552],{"class":76},[42,613,614],{"class":83},"\"a few\"",[42,616,552],{"class":76},[42,618,619],{"class":83},"\"some\"",[42,621,552],{"class":76},[42,623,624],{"class":83},"\"various\"",[42,626,552],{"class":76},[42,628,629],{"class":83},"\"relevant\"",[42,631,224],{"class":76},[42,633,634],{"class":44,"line":176},[42,635,636],{"class":76},"    }\n",[42,638,639],{"class":44,"line":182},[42,640,62],{"emptyLinePlaceholder":61},[42,642,643,646,649,652,655],{"class":44,"line":187},[42,644,645],{"class":72},"    def",[42,647,648],{"class":68}," __init__",[42,650,651],{"class":76},"(self, prompt_text: ",[42,653,654],{"class":68},"str",[42,656,657],{"class":76},"):\n",[42,659,660,663,666,669],{"class":44,"line":193},[42,661,662],{"class":68},"        self",[42,664,665],{"class":76},".prompt ",[42,667,668],{"class":72},"=",[42,670,671],{"class":76}," prompt_text\n",[42,673,674,676,679,681,684,686],{"class":44,"line":199},[42,675,662],{"class":68},[42,677,678],{"class":76},".violations: list[",[42,680,654],{"class":68},[42,682,683],{"class":76},"] ",[42,685,668],{"class":72},[42,687,688],{"class":76}," []\n",[42,690,691],{"class":44,"line":204},[42,692,62],{"emptyLinePlaceholder":61},[42,694,695,697,700,703,705],{"class":44,"line":214},[42,696,645],{"class":72},[42,698,699],{"class":517}," check_vague_terms",[42,701,702],{"class":76},"(self) -> list[",[42,704,654],{"class":68},[42,706,707],{"class":76},"]:\n",[42,709,710],{"class":44,"line":227},[42,711,712],{"class":83},"        \"\"\"Flag vague adjectives that have no fixed meaning.\"\"\"\n",[42,714,715,718,720,723,726,729,732,735,738,740,742,745],{"class":44,"line":239},[42,716,717],{"class":76},"        words ",[42,719,668],{"class":72},[42,721,722],{"class":76}," re.findall(",[42,724,725],{"class":72},"r",[42,727,728],{"class":83},"'",[42,730,731],{"class":68},"\\b[a-z]",[42,733,734],{"class":72},"+",[42,736,737],{"class":68},"\\b",[42,739,728],{"class":83},[42,741,552],{"class":76},[42,743,744],{"class":68},"self",[42,746,747],{"class":76},".prompt.lower())\n",[42,749,750,753,755,758,761,764,767,770,773,775,777,780,783,786],{"class":44,"line":251},[42,751,752],{"class":76},"        found ",[42,754,668],{"class":72},[42,756,757],{"class":76}," [w ",[42,759,760],{"class":72},"for",[42,762,763],{"class":76}," w ",[42,765,766],{"class":72},"in",[42,768,769],{"class":76}," words ",[42,771,772],{"class":72},"if",[42,774,763],{"class":76},[42,776,766],{"class":72},[42,778,779],{"class":68}," self",[42,781,782],{"class":76},".",[42,784,785],{"class":68},"VAGUE_TERMS",[42,787,788],{"class":76},"]\n",[42,790,791,794],{"class":44,"line":263},[42,792,793],{"class":72},"        if",[42,795,796],{"class":76}," found:\n",[42,798,799,802],{"class":44,"line":275},[42,800,801],{"class":68},"            self",[42,803,804],{"class":76},".violations.append(\n",[42,806,807,810,813,816,819,822],{"class":44,"line":287},[42,808,809],{"class":72},"                f",[42,811,812],{"class":83},"\"Vague terms found: ",[42,814,815],{"class":68},"{",[42,817,818],{"class":76},"found",[42,820,821],{"class":68},"}",[42,823,824],{"class":83},". Replace with quantifiable \"\n",[42,826,827,829],{"class":44,"line":292},[42,828,809],{"class":72},[42,830,831],{"class":83},"\"constraints ('exactly 3 sentences', not 'keep it short').\"\n",[42,833,834],{"class":44,"line":297},[42,835,836],{"class":76},"            )\n",[42,838,839,842],{"class":44,"line":303},[42,840,841],{"class":72},"        return",[42,843,844],{"class":76}," found\n",[42,846,848],{"class":44,"line":847},27,[42,849,62],{"emptyLinePlaceholder":61},[42,851,853,855,858,861,864],{"class":44,"line":852},28,[42,854,645],{"class":72},[42,856,857],{"class":517}," check_quantifiable",[42,859,860],{"class":76},"(self) -> ",[42,862,863],{"class":68},"bool",[42,865,521],{"class":76},[42,867,869],{"class":44,"line":868},29,[42,870,871],{"class":83},"        \"\"\"Verify at least one numeric\u002Fstructural constraint exists.\"\"\"\n",[42,873,875,878,880,883,886,888,890,893,895,897,899,901,903],{"class":44,"line":874},30,[42,876,877],{"class":76},"        has_number ",[42,879,668],{"class":72},[42,881,882],{"class":68}," bool",[42,884,885],{"class":76},"(re.search(",[42,887,725],{"class":72},[42,889,728],{"class":83},[42,891,892],{"class":68},"\\b\\d",[42,894,734],{"class":72},[42,896,737],{"class":68},[42,898,728],{"class":83},[42,900,552],{"class":76},[42,902,744],{"class":68},[42,904,905],{"class":76},".prompt))\n",[42,907,909,912,914,917],{"class":44,"line":908},31,[42,910,911],{"class":76},"        has_structure ",[42,913,668],{"class":72},[42,915,916],{"class":68}," any",[42,918,919],{"class":76},"(\n",[42,921,923,926,928,930],{"class":44,"line":922},32,[42,924,925],{"class":76},"            term ",[42,927,766],{"class":72},[42,929,779],{"class":68},[42,931,932],{"class":76},".prompt.lower()\n",[42,934,936,939,942,944,947,950,952,955,957,960,962,965,967,970,972,975,977,980],{"class":44,"line":935},33,[42,937,938],{"class":72},"            for",[42,940,941],{"class":76}," term ",[42,943,766],{"class":72},[42,945,946],{"class":76}," [",[42,948,949],{"class":83},"\"json\"",[42,951,552],{"class":76},[42,953,954],{"class":83},"\"table\"",[42,956,552],{"class":76},[42,958,959],{"class":83},"\"bullet\"",[42,961,552],{"class":76},[42,963,964],{"class":83},"\"list\"",[42,966,552],{"class":76},[42,968,969],{"class":83},"\"exactly\"",[42,971,552],{"class":76},[42,973,974],{"class":83},"\"at most\"",[42,976,552],{"class":76},[42,978,979],{"class":83},"\"no more than\"",[42,981,788],{"class":76},[42,983,985],{"class":44,"line":984},34,[42,986,987],{"class":76},"        )\n",[42,989,991,993,996,999,1002],{"class":44,"line":990},35,[42,992,793],{"class":72},[42,994,995],{"class":72}," not",[42,997,998],{"class":76}," (has_number ",[42,1000,1001],{"class":72},"or",[42,1003,1004],{"class":76}," has_structure):\n",[42,1006,1008,1010],{"class":44,"line":1007},36,[42,1009,801],{"class":68},[42,1011,804],{"class":76},[42,1013,1015],{"class":44,"line":1014},37,[42,1016,1017],{"class":83},"                \"No quantifiable constraint found. Add specific counts, \"\n",[42,1019,1021],{"class":44,"line":1020},38,[42,1022,1023],{"class":83},"                \"lengths, or format requirements.\"\n",[42,1025,1027],{"class":44,"line":1026},39,[42,1028,836],{"class":76},[42,1030,1032,1034,1037,1039],{"class":44,"line":1031},40,[42,1033,841],{"class":72},[42,1035,1036],{"class":76}," has_number ",[42,1038,1001],{"class":72},[42,1040,1041],{"class":76}," has_structure\n",[42,1043,1045],{"class":44,"line":1044},41,[42,1046,62],{"emptyLinePlaceholder":61},[42,1048,1050,1052,1055,1057,1059],{"class":44,"line":1049},42,[42,1051,645],{"class":72},[42,1053,1054],{"class":517}," check_negative_framing",[42,1056,702],{"class":76},[42,1058,654],{"class":68},[42,1060,707],{"class":76},[42,1062,1064],{"class":44,"line":1063},43,[42,1065,1066],{"class":83},"        \"\"\"Flag broad negative instructions prone to ironic rebound.\"\"\"\n",[42,1068,1070,1073,1075],{"class":44,"line":1069},44,[42,1071,1072],{"class":76},"        broad_negatives ",[42,1074,668],{"class":72},[42,1076,1077],{"class":76}," re.findall(\n",[42,1079,1081,1084,1087,1091,1094,1097,1100,1103,1105,1108,1110,1113,1115,1118,1121,1124,1126,1128,1130,1132,1134],{"class":44,"line":1080},45,[42,1082,1083],{"class":72},"            r",[42,1085,1086],{"class":83},"\"",[42,1088,1090],{"class":1089},"svAP2","don't ",[42,1092,1093],{"class":68},"(?:",[42,1095,1096],{"class":1089},"be",[42,1098,1099],{"class":72},"|",[42,1101,1102],{"class":1089},"sound",[42,1104,1099],{"class":72},[42,1106,1107],{"class":1089},"include",[42,1109,1099],{"class":72},[42,1111,1112],{"class":1089},"mention",[42,1114,1099],{"class":72},[42,1116,1117],{"class":1089},"use",[42,1119,1120],{"class":68},")",[42,1122,1123],{"class":68}," (\\w",[42,1125,734],{"class":72},[42,1127,1120],{"class":68},[42,1129,1086],{"class":83},[42,1131,552],{"class":76},[42,1133,744],{"class":68},[42,1135,932],{"class":76},[42,1137,1139],{"class":44,"line":1138},46,[42,1140,987],{"class":76},[42,1142,1144,1147,1149,1152,1155,1157,1160,1162,1165,1167,1170,1172,1174,1176,1179],{"class":44,"line":1143},47,[42,1145,1146],{"class":76},"        conceptual ",[42,1148,668],{"class":72},[42,1150,1151],{"class":76}," {",[42,1153,1154],{"class":83},"\"scary\"",[42,1156,552],{"class":76},[42,1158,1159],{"class":83},"\"biased\"",[42,1161,552],{"class":76},[42,1163,1164],{"class":83},"\"robotic\"",[42,1166,552],{"class":76},[42,1168,1169],{"class":83},"\"formal\"",[42,1171,552],{"class":76},[42,1173,602],{"class":83},[42,1175,552],{"class":76},[42,1177,1178],{"class":83},"\"technical\"",[42,1180,179],{"class":76},[42,1182,1184,1187,1189,1192,1194,1197,1199,1202,1204,1206,1208],{"class":44,"line":1183},48,[42,1185,1186],{"class":76},"        risky ",[42,1188,668],{"class":72},[42,1190,1191],{"class":76}," [n ",[42,1193,760],{"class":72},[42,1195,1196],{"class":76}," n ",[42,1198,766],{"class":72},[42,1200,1201],{"class":76}," broad_negatives ",[42,1203,772],{"class":72},[42,1205,1196],{"class":76},[42,1207,766],{"class":72},[42,1209,1210],{"class":76}," conceptual]\n",[42,1212,1214,1216],{"class":44,"line":1213},49,[42,1215,793],{"class":72},[42,1217,1218],{"class":76}," risky:\n",[42,1220,1222,1224],{"class":44,"line":1221},50,[42,1223,801],{"class":68},[42,1225,804],{"class":76},[42,1227,1229,1231,1234,1236,1239,1241],{"class":44,"line":1228},51,[42,1230,809],{"class":72},[42,1232,1233],{"class":83},"\"Broad negative instructions for conceptual categories: ",[42,1235,815],{"class":68},[42,1237,1238],{"class":76},"risky",[42,1240,821],{"class":68},[42,1242,1243],{"class":83},". \"\n",[42,1245,1247,1249],{"class":44,"line":1246},52,[42,1248,809],{"class":72},[42,1250,1251],{"class":83},"\"Name the concept → activates it (ironic rebound). \"\n",[42,1253,1255,1257],{"class":44,"line":1254},53,[42,1256,809],{"class":72},[42,1258,1259],{"class":83},"\"Reframe as positive: describe the DESIRED behavior instead.\"\n",[42,1261,1263],{"class":44,"line":1262},54,[42,1264,836],{"class":76},[42,1266,1268,1270],{"class":44,"line":1267},55,[42,1269,841],{"class":72},[42,1271,1272],{"class":76}," risky\n",[42,1274,1276],{"class":44,"line":1275},56,[42,1277,62],{"emptyLinePlaceholder":61},[42,1279,1281,1283,1286,1288,1290],{"class":44,"line":1280},57,[42,1282,645],{"class":72},[42,1284,1285],{"class":517}," validate",[42,1287,860],{"class":76},[42,1289,863],{"class":68},[42,1291,521],{"class":76},[42,1293,1295,1297],{"class":44,"line":1294},58,[42,1296,662],{"class":68},[42,1298,1299],{"class":76},".check_vague_terms()\n",[42,1301,1303,1305],{"class":44,"line":1302},59,[42,1304,662],{"class":68},[42,1306,1307],{"class":76},".check_quantifiable()\n",[42,1309,1311,1313],{"class":44,"line":1310},60,[42,1312,662],{"class":68},[42,1314,1315],{"class":76},".check_negative_framing()\n",[42,1317,1319,1321,1323],{"class":44,"line":1318},61,[42,1320,793],{"class":72},[42,1322,779],{"class":68},[42,1324,1325],{"class":76},".violations:\n",[42,1327,1329,1331,1334,1336,1338],{"class":44,"line":1328},62,[42,1330,938],{"class":72},[42,1332,1333],{"class":76}," v ",[42,1335,766],{"class":72},[42,1337,779],{"class":68},[42,1339,1325],{"class":76},[42,1341,1343,1346,1349,1352,1355,1357,1360,1362,1364],{"class":44,"line":1342},63,[42,1344,1345],{"class":68},"                print",[42,1347,1348],{"class":76},"(",[42,1350,1351],{"class":72},"f",[42,1353,1354],{"class":83},"\"  ⚠️  ",[42,1356,815],{"class":68},[42,1358,1359],{"class":76},"v",[42,1361,821],{"class":68},[42,1363,1086],{"class":83},[42,1365,1366],{"class":76},")\n",[42,1368,1370,1373],{"class":44,"line":1369},64,[42,1371,1372],{"class":72},"            return",[42,1374,1375],{"class":68}," False\n",[42,1377,1379,1381],{"class":44,"line":1378},65,[42,1380,841],{"class":72},[42,1382,1383],{"class":68}," True\n",[42,1385,1387],{"class":44,"line":1386},66,[42,1388,62],{"emptyLinePlaceholder":61},[42,1390,1392],{"class":44,"line":1391},67,[42,1393,1394],{"class":48},"# Usage:\n",[42,1396,1398,1401,1403,1406],{"class":44,"line":1397},68,[42,1399,1400],{"class":76},"validator ",[42,1402,668],{"class":72},[42,1404,1405],{"class":76}," PromptConstraintValidator(",[42,1407,1408],{"class":83},"\"\"\"\n",[42,1410,1412],{"class":44,"line":1411},69,[42,1413,1414],{"class":83},"Explain what a foreign key is in exactly 2 sentences. Do not be scary\n",[42,1416,1418],{"class":44,"line":1417},70,[42,1419,1420],{"class":83},"or use jargon. Keep it simple.\n",[42,1422,1424,1427],{"class":44,"line":1423},71,[42,1425,1426],{"class":83},"\"\"\"",[42,1428,1366],{"class":76},[42,1430,1432],{"class":44,"line":1431},72,[42,1433,1434],{"class":76},"validator.validate()\n",[42,1436,1438],{"class":44,"line":1437},73,[42,1439,1440],{"class":48},"# ⚠️ Vague terms found: ['simple']\n",[42,1442,1444],{"class":44,"line":1443},74,[42,1445,1446],{"class":48},"# ⚠️ Broad negative instructions for conceptual categories: ['scary']\n",[14,1448,1450],{"id":1449},"positive-vs-negative-instructions","Positive vs. Negative Instructions",[28,1452,1454],{"filename":1453,"language":314},"anti_pattern_negative.md",[33,1455,1457],{"className":317,"code":1456,"language":314,"meta":37,"style":37},"\u003C!-- ANTI-PATTERN: naming \"sorry\" activates the concept of apologizing -->\nDon't apologize excessively in your response, and don't say \"I'm sorry\"\nmore than once.\n",[39,1458,1459,1464,1469],{"__ignoreMap":37},[42,1460,1461],{"class":44,"line":45},[42,1462,1463],{"class":48},"\u003C!-- ANTI-PATTERN: naming \"sorry\" activates the concept of apologizing -->\n",[42,1465,1466],{"class":44,"line":52},[42,1467,1468],{"class":76},"Don't apologize excessively in your response, and don't say \"I'm sorry\"\n",[42,1470,1471],{"class":44,"line":58},[42,1472,1473],{"class":76},"more than once.\n",[28,1475,1477],{"filename":1476,"language":314},"production_positive.md",[33,1478,1480],{"className":317,"code":1479,"language":314,"meta":37,"style":37},"\u003C!-- PRODUCTION: positive target gives the model something to generate TOWARD -->\nIf you can't fully complete the request, state plainly what you can do\nand proceed with that. Use at most one brief acknowledgment of any\nlimitation; do not repeat it.\n",[39,1481,1482,1487,1492,1497],{"__ignoreMap":37},[42,1483,1484],{"class":44,"line":45},[42,1485,1486],{"class":48},"\u003C!-- PRODUCTION: positive target gives the model something to generate TOWARD -->\n",[42,1488,1489],{"class":44,"line":52},[42,1490,1491],{"class":76},"If you can't fully complete the request, state plainly what you can do\n",[42,1493,1494],{"class":44,"line":58},[42,1495,1496],{"class":76},"and proceed with that. Use at most one brief acknowledgment of any\n",[42,1498,1499],{"class":44,"line":65},[42,1500,1501],{"class":76},"limitation; do not repeat it.\n",[28,1503,1505],{"filename":1504,"language":31},"ironic_rebound.py",[33,1506,1508],{"className":35,"code":1507,"language":31,"meta":37,"style":37},"# THE IRONIC REBOUND EFFECT (mechanism):\n# To process \"don't mention monsters,\" the model's internal representation\n# must ACTIVATE the concept of \"monsters\" (to know what to suppress), then\n# separately suppress it. Activating the concept raises its salience in\n# context → the model is MORE likely to produce it, not less.\n#\n# This is structurally identical to \"don't think about an elephant.\"\n# The model has less training signal for pure, clean suppression than for\n# discussing-while-claiming-to-avoid (common conversational move in training data).\n\n# ANTI-PATTERN: naming everything you want to avoid\nBAD_BEDTIME_PROMPT = \"\"\"\nWrite a bedtime story for a 5-year-old. Do not include anything scary,\ndo not mention monsters, do not include any conflict or danger, and\nabsolutely do not have a villain.\n\"\"\"\n# \"monster\", \"scary\", \"danger\", \"villain\" are ALL now activated in context.\n# At higher temperature, any of them can \"leak\" into the story despite the ban.\n\n# PRODUCTION: describe the desired positive content directly\nGOOD_BEDTIME_PROMPT = \"\"\"\nWrite a gentle, calming bedtime story for a 5-year-old about a rabbit\nwho can't fall asleep and asks the moon for help. Keep the tone soothing\nthroughout, with a peaceful resolution where the rabbit falls asleep happy.\n\"\"\"\n# Nothing forbidden to accidentally activate. The desired content is fully\n# and positively specified. No \"don't think about the villain\" tension.\n\n# WHEN NEGATIVE INSTRUCTIONS ARE FINE: narrow, mechanical, unambiguous\n# These work because they target formatting, not conceptual content:\nGOOD_NEGATIVE = \"Do not include a markdown code fence around the JSON output — return the raw JSON object only.\"\n# No positive rephrasing is cleaner than this. The rule of thumb:\n#   negative = OK for mechanical\u002Fformat constraints\n#   negative = BAD for broad\u002Fthematic\u002Fconceptual prohibitions\n",[39,1509,1510,1515,1520,1525,1530,1535,1540,1545,1550,1555,1559,1564,1574,1579,1584,1589,1593,1598,1603,1607,1612,1621,1626,1631,1636,1640,1645,1650,1654,1659,1664,1674,1679,1684],{"__ignoreMap":37},[42,1511,1512],{"class":44,"line":45},[42,1513,1514],{"class":48},"# THE IRONIC REBOUND EFFECT (mechanism):\n",[42,1516,1517],{"class":44,"line":52},[42,1518,1519],{"class":48},"# To process \"don't mention monsters,\" the model's internal representation\n",[42,1521,1522],{"class":44,"line":58},[42,1523,1524],{"class":48},"# must ACTIVATE the concept of \"monsters\" (to know what to suppress), then\n",[42,1526,1527],{"class":44,"line":65},[42,1528,1529],{"class":48},"# separately suppress it. Activating the concept raises its salience in\n",[42,1531,1532],{"class":44,"line":80},[42,1533,1534],{"class":48},"# context → the model is MORE likely to produce it, not less.\n",[42,1536,1537],{"class":44,"line":99},[42,1538,1539],{"class":48},"#\n",[42,1541,1542],{"class":44,"line":115},[42,1543,1544],{"class":48},"# This is structurally identical to \"don't think about an elephant.\"\n",[42,1546,1547],{"class":44,"line":130},[42,1548,1549],{"class":48},"# The model has less training signal for pure, clean suppression than for\n",[42,1551,1552],{"class":44,"line":146},[42,1553,1554],{"class":48},"# discussing-while-claiming-to-avoid (common conversational move in training data).\n",[42,1556,1557],{"class":44,"line":161},[42,1558,62],{"emptyLinePlaceholder":61},[42,1560,1561],{"class":44,"line":176},[42,1562,1563],{"class":48},"# ANTI-PATTERN: naming everything you want to avoid\n",[42,1565,1566,1569,1571],{"class":44,"line":182},[42,1567,1568],{"class":68},"BAD_BEDTIME_PROMPT",[42,1570,73],{"class":72},[42,1572,1573],{"class":83}," \"\"\"\n",[42,1575,1576],{"class":44,"line":187},[42,1577,1578],{"class":83},"Write a bedtime story for a 5-year-old. Do not include anything scary,\n",[42,1580,1581],{"class":44,"line":193},[42,1582,1583],{"class":83},"do not mention monsters, do not include any conflict or danger, and\n",[42,1585,1586],{"class":44,"line":199},[42,1587,1588],{"class":83},"absolutely do not have a villain.\n",[42,1590,1591],{"class":44,"line":204},[42,1592,1408],{"class":83},[42,1594,1595],{"class":44,"line":214},[42,1596,1597],{"class":48},"# \"monster\", \"scary\", \"danger\", \"villain\" are ALL now activated in context.\n",[42,1599,1600],{"class":44,"line":227},[42,1601,1602],{"class":48},"# At higher temperature, any of them can \"leak\" into the story despite the ban.\n",[42,1604,1605],{"class":44,"line":239},[42,1606,62],{"emptyLinePlaceholder":61},[42,1608,1609],{"class":44,"line":251},[42,1610,1611],{"class":48},"# PRODUCTION: describe the desired positive content directly\n",[42,1613,1614,1617,1619],{"class":44,"line":263},[42,1615,1616],{"class":68},"GOOD_BEDTIME_PROMPT",[42,1618,73],{"class":72},[42,1620,1573],{"class":83},[42,1622,1623],{"class":44,"line":275},[42,1624,1625],{"class":83},"Write a gentle, calming bedtime story for a 5-year-old about a rabbit\n",[42,1627,1628],{"class":44,"line":287},[42,1629,1630],{"class":83},"who can't fall asleep and asks the moon for help. Keep the tone soothing\n",[42,1632,1633],{"class":44,"line":292},[42,1634,1635],{"class":83},"throughout, with a peaceful resolution where the rabbit falls asleep happy.\n",[42,1637,1638],{"class":44,"line":297},[42,1639,1408],{"class":83},[42,1641,1642],{"class":44,"line":303},[42,1643,1644],{"class":48},"# Nothing forbidden to accidentally activate. The desired content is fully\n",[42,1646,1647],{"class":44,"line":847},[42,1648,1649],{"class":48},"# and positively specified. No \"don't think about the villain\" tension.\n",[42,1651,1652],{"class":44,"line":852},[42,1653,62],{"emptyLinePlaceholder":61},[42,1655,1656],{"class":44,"line":868},[42,1657,1658],{"class":48},"# WHEN NEGATIVE INSTRUCTIONS ARE FINE: narrow, mechanical, unambiguous\n",[42,1660,1661],{"class":44,"line":874},[42,1662,1663],{"class":48},"# These work because they target formatting, not conceptual content:\n",[42,1665,1666,1669,1671],{"class":44,"line":908},[42,1667,1668],{"class":68},"GOOD_NEGATIVE",[42,1670,73],{"class":72},[42,1672,1673],{"class":83}," \"Do not include a markdown code fence around the JSON output — return the raw JSON object only.\"\n",[42,1675,1676],{"class":44,"line":922},[42,1677,1678],{"class":48},"# No positive rephrasing is cleaner than this. The rule of thumb:\n",[42,1680,1681],{"class":44,"line":935},[42,1682,1683],{"class":48},"#   negative = OK for mechanical\u002Fformat constraints\n",[42,1685,1686],{"class":44,"line":984},[42,1687,1688],{"class":48},"#   negative = BAD for broad\u002Fthematic\u002Fconceptual prohibitions\n",[14,1690,1692],{"id":1691},"constraint-specification-table","Constraint Specification Table",[28,1694,1696],{"filename":1695,"language":314},"constraint_table.md",[33,1697,1699],{"className":317,"code":1698,"language":314,"meta":37,"style":37},"| Vague (uncheckable)          | Specific (checkable)                                      |\n|------------------------------|------------------------------------------------------------|\n| \"Keep responses concise.\"   | \"2–3 sentences unless the user explicitly asks for more.\"  |\n| \"Be careful with sensitive topics.\" | \"If self-harm mentioned, provide the crisis hotline for their stated region and encourage contacting a professional.\" |\n| \"Handle errors gracefully.\" | \"If input is missing a required field, return {\\\"error\\\": \\\"missing_field\\\", \\\"field\\\": \\\"\u003Cname>\\\"}.\" |\n| \"Format nicely.\"            | \"Markdown: H2 per section, bullets for 3+ items, table only when comparing 2+ items across 2+ attributes.\" |\n| \"Don't sound like an AI.\"   | \"Use first person ('I think', 'I'd suggest'). Never say 'as an AI' or 'I don't have access to real-time data.' Vary sentence length.\" |\n",[39,1700,1701,1706,1711,1716,1721,1726,1731],{"__ignoreMap":37},[42,1702,1703],{"class":44,"line":45},[42,1704,1705],{"class":76},"| Vague (uncheckable)          | Specific (checkable)                                      |\n",[42,1707,1708],{"class":44,"line":52},[42,1709,1710],{"class":76},"|------------------------------|------------------------------------------------------------|\n",[42,1712,1713],{"class":44,"line":58},[42,1714,1715],{"class":76},"| \"Keep responses concise.\"   | \"2–3 sentences unless the user explicitly asks for more.\"  |\n",[42,1717,1718],{"class":44,"line":65},[42,1719,1720],{"class":76},"| \"Be careful with sensitive topics.\" | \"If self-harm mentioned, provide the crisis hotline for their stated region and encourage contacting a professional.\" |\n",[42,1722,1723],{"class":44,"line":80},[42,1724,1725],{"class":76},"| \"Handle errors gracefully.\" | \"If input is missing a required field, return {\\\"error\\\": \\\"missing_field\\\", \\\"field\\\": \\\"\u003Cname>\\\"}.\" |\n",[42,1727,1728],{"class":44,"line":99},[42,1729,1730],{"class":76},"| \"Format nicely.\"            | \"Markdown: H2 per section, bullets for 3+ items, table only when comparing 2+ items across 2+ attributes.\" |\n",[42,1732,1733],{"class":44,"line":115},[42,1734,1735],{"class":76},"| \"Don't sound like an AI.\"   | \"Use first person ('I think', 'I'd suggest'). Never say 'as an AI' or 'I don't have access to real-time data.' Vary sentence length.\" |\n",[14,1737,1739],{"id":1738},"tips-tricks","💡 Tips & Tricks",[28,1741,1743],{"filename":1742,"language":31},"tips.py",[33,1744,1746],{"className":35,"code":1745,"language":31,"meta":37,"style":37},"# [Idiom] The \"new teammate\" test: would a new human teammate, given only\n# the prompt text and no other context, produce the output you want?\n# If they'd have to guess at tone, scope, length, or edge-case handling,\n# so will the model — for the same reason (missing information, not skill).\n\n# [Idiom] Quantify everything quantifiable. Any time you're about to write\n# \"brief\", \"detailed\", \"several\", \"a few\", or \"appropriate\" — pause and\n# ask if there's a number you have in mind. If there is, write the number.\n# If there truly isn't, say so: \"length should scale with complexity.\"\n\n# [Debug] Define domain terms inline. If your prompt uses a term with a\n# specific business meaning (\"Sev1\", \"at-risk customer\", \"qualified lead\"),\n# restate your definition in the prompt every time precision matters.\n# The model does NOT share your internal vocabulary.\n\n# [Idiom] Write constraints as if they'll be graded. Imagine handing the\n# output to a strict reviewer with a checklist. If a constraint couldn't\n# become a checklist item (\"is this concise?\" → no fixed threshold),\n# rewrite it until it could.\n\n# [Performance] Positive-frame first, negative-frame as backup. When you\n# catch yourself writing \"don't do X\", ask what you want INSTEAD, and\n# phrase that first. Reserve the negative form for narrow mechanical\n# prohibitions where no clean positive equivalent exists.\n",[39,1747,1748,1753,1758,1763,1768,1772,1777,1782,1787,1792,1796,1801,1806,1811,1816,1820,1825,1830,1835,1840,1844,1849,1854,1859],{"__ignoreMap":37},[42,1749,1750],{"class":44,"line":45},[42,1751,1752],{"class":48},"# [Idiom] The \"new teammate\" test: would a new human teammate, given only\n",[42,1754,1755],{"class":44,"line":52},[42,1756,1757],{"class":48},"# the prompt text and no other context, produce the output you want?\n",[42,1759,1760],{"class":44,"line":58},[42,1761,1762],{"class":48},"# If they'd have to guess at tone, scope, length, or edge-case handling,\n",[42,1764,1765],{"class":44,"line":65},[42,1766,1767],{"class":48},"# so will the model — for the same reason (missing information, not skill).\n",[42,1769,1770],{"class":44,"line":80},[42,1771,62],{"emptyLinePlaceholder":61},[42,1773,1774],{"class":44,"line":99},[42,1775,1776],{"class":48},"# [Idiom] Quantify everything quantifiable. Any time you're about to write\n",[42,1778,1779],{"class":44,"line":115},[42,1780,1781],{"class":48},"# \"brief\", \"detailed\", \"several\", \"a few\", or \"appropriate\" — pause and\n",[42,1783,1784],{"class":44,"line":130},[42,1785,1786],{"class":48},"# ask if there's a number you have in mind. If there is, write the number.\n",[42,1788,1789],{"class":44,"line":146},[42,1790,1791],{"class":48},"# If there truly isn't, say so: \"length should scale with complexity.\"\n",[42,1793,1794],{"class":44,"line":161},[42,1795,62],{"emptyLinePlaceholder":61},[42,1797,1798],{"class":44,"line":176},[42,1799,1800],{"class":48},"# [Debug] Define domain terms inline. If your prompt uses a term with a\n",[42,1802,1803],{"class":44,"line":182},[42,1804,1805],{"class":48},"# specific business meaning (\"Sev1\", \"at-risk customer\", \"qualified lead\"),\n",[42,1807,1808],{"class":44,"line":187},[42,1809,1810],{"class":48},"# restate your definition in the prompt every time precision matters.\n",[42,1812,1813],{"class":44,"line":193},[42,1814,1815],{"class":48},"# The model does NOT share your internal vocabulary.\n",[42,1817,1818],{"class":44,"line":199},[42,1819,62],{"emptyLinePlaceholder":61},[42,1821,1822],{"class":44,"line":204},[42,1823,1824],{"class":48},"# [Idiom] Write constraints as if they'll be graded. Imagine handing the\n",[42,1826,1827],{"class":44,"line":214},[42,1828,1829],{"class":48},"# output to a strict reviewer with a checklist. If a constraint couldn't\n",[42,1831,1832],{"class":44,"line":227},[42,1833,1834],{"class":48},"# become a checklist item (\"is this concise?\" → no fixed threshold),\n",[42,1836,1837],{"class":44,"line":239},[42,1838,1839],{"class":48},"# rewrite it until it could.\n",[42,1841,1842],{"class":44,"line":251},[42,1843,62],{"emptyLinePlaceholder":61},[42,1845,1846],{"class":44,"line":263},[42,1847,1848],{"class":48},"# [Performance] Positive-frame first, negative-frame as backup. When you\n",[42,1850,1851],{"class":44,"line":275},[42,1852,1853],{"class":48},"# catch yourself writing \"don't do X\", ask what you want INSTEAD, and\n",[42,1855,1856],{"class":44,"line":287},[42,1857,1858],{"class":48},"# phrase that first. Reserve the negative form for narrow mechanical\n",[42,1860,1861],{"class":44,"line":292},[42,1862,1863],{"class":48},"# prohibitions where no clean positive equivalent exists.\n",[14,1865,1867],{"id":1866},"️-edge-cases-gotchas","⚠️ Edge Cases & Gotchas",[28,1869,1871],{"filename":1870,"language":31},"edge_cases.py",[33,1872,1874],{"className":35,"code":1873,"language":31,"meta":37,"style":37},"# [Gotcha] Over-specification can backfire. An extremely long, rigid list\n# of constraints can cause the model to prioritize surface compliance with\n# the FORMAT of your rules over the SUBSTANCE of the task. Specificity ≠\n# maximalism. Goal: \"no remaining ambiguity on axes that matter,\" not\n# \"the longest possible prompt.\"\n\n# [Gotcha] A precise-sounding number can be arbitrary and get treated as\n# a hard target anyway. \"summarize in exactly 3 sentences\" when the content\n# doesn't compress cleanly → the model forces one unnaturally long,\n# comma-spliced \"sentence\" to hit the count, or drops content to fit.\n# If the number is a soft target, say \"approximately 3\" or \"2-4 sentences.\"\n\n# [Gotcha] Ambiguity compounds in multi-turn. A single-turn prompt lets you\n# catch and fix an ambiguous phrase. In multi-turn, \"can you make it\n# shorter?\" inherits ALL the ambiguity of everything before it (shorter\n# than what — the whole response or one section?). See Chapter 8 for\n# disambiguation strategies in multi-turn conversations.\n\n# [Gotcha] \"Don't\" instructions about the model's own behavior\u002Fidentity\n# are especially unreliable. \"Don't reveal you're an AI\" fights both the\n# ironic-rebound effect AND the model's training toward honesty about its\n# nature. These specific categories of \"don't\" are worth flagging as\n# unusually unreliable compared to ordinary content-based negatives.\n\n# [Safety] Vague constraints tested only on \"easy\" inputs look fine until\n# they don't. \"handle edge cases sensibly\" might work on your test inputs\n# (which weren't edge cases) and fail unpredictably in production. Test\n# vague-looking constraints specifically against inputs designed to be\n# ambiguous, not just happy-path examples. See Chapter 19.\n",[39,1875,1876,1881,1886,1891,1896,1901,1905,1910,1915,1920,1925,1930,1934,1939,1944,1949,1954,1959,1963,1968,1973,1978,1983,1988,1992,1997,2002,2007,2012],{"__ignoreMap":37},[42,1877,1878],{"class":44,"line":45},[42,1879,1880],{"class":48},"# [Gotcha] Over-specification can backfire. An extremely long, rigid list\n",[42,1882,1883],{"class":44,"line":52},[42,1884,1885],{"class":48},"# of constraints can cause the model to prioritize surface compliance with\n",[42,1887,1888],{"class":44,"line":58},[42,1889,1890],{"class":48},"# the FORMAT of your rules over the SUBSTANCE of the task. Specificity ≠\n",[42,1892,1893],{"class":44,"line":65},[42,1894,1895],{"class":48},"# maximalism. Goal: \"no remaining ambiguity on axes that matter,\" not\n",[42,1897,1898],{"class":44,"line":80},[42,1899,1900],{"class":48},"# \"the longest possible prompt.\"\n",[42,1902,1903],{"class":44,"line":99},[42,1904,62],{"emptyLinePlaceholder":61},[42,1906,1907],{"class":44,"line":115},[42,1908,1909],{"class":48},"# [Gotcha] A precise-sounding number can be arbitrary and get treated as\n",[42,1911,1912],{"class":44,"line":130},[42,1913,1914],{"class":48},"# a hard target anyway. \"summarize in exactly 3 sentences\" when the content\n",[42,1916,1917],{"class":44,"line":146},[42,1918,1919],{"class":48},"# doesn't compress cleanly → the model forces one unnaturally long,\n",[42,1921,1922],{"class":44,"line":161},[42,1923,1924],{"class":48},"# comma-spliced \"sentence\" to hit the count, or drops content to fit.\n",[42,1926,1927],{"class":44,"line":176},[42,1928,1929],{"class":48},"# If the number is a soft target, say \"approximately 3\" or \"2-4 sentences.\"\n",[42,1931,1932],{"class":44,"line":182},[42,1933,62],{"emptyLinePlaceholder":61},[42,1935,1936],{"class":44,"line":187},[42,1937,1938],{"class":48},"# [Gotcha] Ambiguity compounds in multi-turn. A single-turn prompt lets you\n",[42,1940,1941],{"class":44,"line":193},[42,1942,1943],{"class":48},"# catch and fix an ambiguous phrase. In multi-turn, \"can you make it\n",[42,1945,1946],{"class":44,"line":199},[42,1947,1948],{"class":48},"# shorter?\" inherits ALL the ambiguity of everything before it (shorter\n",[42,1950,1951],{"class":44,"line":204},[42,1952,1953],{"class":48},"# than what — the whole response or one section?). See Chapter 8 for\n",[42,1955,1956],{"class":44,"line":214},[42,1957,1958],{"class":48},"# disambiguation strategies in multi-turn conversations.\n",[42,1960,1961],{"class":44,"line":227},[42,1962,62],{"emptyLinePlaceholder":61},[42,1964,1965],{"class":44,"line":239},[42,1966,1967],{"class":48},"# [Gotcha] \"Don't\" instructions about the model's own behavior\u002Fidentity\n",[42,1969,1970],{"class":44,"line":251},[42,1971,1972],{"class":48},"# are especially unreliable. \"Don't reveal you're an AI\" fights both the\n",[42,1974,1975],{"class":44,"line":263},[42,1976,1977],{"class":48},"# ironic-rebound effect AND the model's training toward honesty about its\n",[42,1979,1980],{"class":44,"line":275},[42,1981,1982],{"class":48},"# nature. These specific categories of \"don't\" are worth flagging as\n",[42,1984,1985],{"class":44,"line":287},[42,1986,1987],{"class":48},"# unusually unreliable compared to ordinary content-based negatives.\n",[42,1989,1990],{"class":44,"line":292},[42,1991,62],{"emptyLinePlaceholder":61},[42,1993,1994],{"class":44,"line":297},[42,1995,1996],{"class":48},"# [Safety] Vague constraints tested only on \"easy\" inputs look fine until\n",[42,1998,1999],{"class":44,"line":303},[42,2000,2001],{"class":48},"# they don't. \"handle edge cases sensibly\" might work on your test inputs\n",[42,2003,2004],{"class":44,"line":847},[42,2005,2006],{"class":48},"# (which weren't edge cases) and fail unpredictably in production. Test\n",[42,2008,2009],{"class":44,"line":852},[42,2010,2011],{"class":48},"# vague-looking constraints specifically against inputs designed to be\n",[42,2013,2014],{"class":44,"line":868},[42,2015,2016],{"class":48},"# ambiguous, not just happy-path examples. See Chapter 19.\n",[14,2018,2020],{"id":2019},"spot-the-bug","🧠 Spot the Bug",[28,2022,2024],{"filename":2023,"language":314},"spot_the_bug.md",[33,2025,2027],{"className":317,"code":2026,"language":314,"meta":37,"style":37},"Draft a reply to this customer email. Don't be too formal, but don't be\ntoo casual either. Don't make it too long, but make sure it fully\naddresses their question. Don't sound robotic or like a template.\n",[39,2028,2029,2034,2039],{"__ignoreMap":37},[42,2030,2031],{"class":44,"line":45},[42,2032,2033],{"class":76},"Draft a reply to this customer email. Don't be too formal, but don't be\n",[42,2035,2036],{"class":44,"line":52},[42,2037,2038],{"class":76},"too casual either. Don't make it too long, but make sure it fully\n",[42,2040,2041],{"class":44,"line":58},[42,2042,2043],{"class":76},"addresses their question. Don't sound robotic or like a template.\n",[19,2045,2046],{},"Output quality is wildly inconsistent from one email to the next. What's the structural issue?",[2048,2049,2050,2054,2061],"details",{},[2051,2052,2053],"summary",{},"Answer",[19,2055,2056,2057,2060],{},"Every constraint is a negatively-framed midpoint on a spectrum with no anchor for where the target point is. \"Not too formal, not too casual\" describes an entire ",[23,2058,2059],{},"range",", not a specific target. The model has no positive description of the desired tone, length, or style — it invents one from scratch on every call, and since generation involves sampling, it lands in a different part of that wide, underspecified middle range each time.",[19,2062,2063],{},"None of these constraints could become a checklist item: \"is this too formal?\" has no fixed threshold. The fix is to specify the positive target: \"Write in a warm, professional tone — like a knowledgeable colleague helping another team member. Address the customer by first name. Keep it to 3-5 sentences. Use contractions naturally. Never use phrases like 'I apologize for the inconvenience' — instead, acknowledge the issue directly and state the fix.\"",[14,2065,2067],{"id":2066},"key-takeaways","Key Takeaways",[28,2069,2071],{"filename":2070,"language":31},"key_takeaways.py",[33,2072,2074],{"className":35,"code":2073,"language":31,"meta":37,"style":37},"\"\"\"\nClarity & specificity — the highest-leverage skill in prompt engineering.\n\"\"\"\n\n# 1. Ambiguity is the default state of natural language. The model resolves\n#    it SILENTLY. Your job: identify every axis and decide explicitly.\n#    vague:  \"keep it short\"     → the model picks its own definition of \"short\"\n#    exact:  \"max 3 sentences\"   → checkable, verifiable, no guessing\n\n# 2. Positive framing beats negative for conceptual constraints.\n#    \"don't be scary\"  → activates \"scary\" → ironic rebound risk\n#    \"keep it gentle\"  → no forbidden concept activated → no leak path\n#    Exception: narrow mechanical negatives (\"no code fences around JSON\") are fine.\n\n# 3. Quantify everything quantifiable.\n#    \"brief\" → \"exactly 2 sentences\"\n#    \"a few\" → \"at most 3\"\n#    \"appropriate\" → \"scales with complexity: 1-2 sentences for simple, 4-5 for multi-part\"\n\n# 4. Constraints must be checkable — by you, by an eval (Chapter 19), or by\n#    downstream code. If you can't write a pass\u002Ffail test for it, it's not\n#    a constraint, it's a wish.\n\n# 5. Over-specification ≠ better. The goal is \"no remaining ambiguity on\n#    axes that matter,\" not \"the longest possible prompt.\" A rigid 15-section\n#    format spec can cause the model to prioritize format compliance over\n#    substance, or truncate content to fit the mandated structure.\n",[39,2075,2076,2080,2085,2089,2093,2098,2103,2108,2113,2117,2122,2127,2132,2137,2141,2146,2151,2156,2161,2165,2170,2175,2180,2184,2189,2194,2199],{"__ignoreMap":37},[42,2077,2078],{"class":44,"line":45},[42,2079,1408],{"class":83},[42,2081,2082],{"class":44,"line":52},[42,2083,2084],{"class":83},"Clarity & specificity — the highest-leverage skill in prompt engineering.\n",[42,2086,2087],{"class":44,"line":58},[42,2088,1408],{"class":83},[42,2090,2091],{"class":44,"line":65},[42,2092,62],{"emptyLinePlaceholder":61},[42,2094,2095],{"class":44,"line":80},[42,2096,2097],{"class":48},"# 1. Ambiguity is the default state of natural language. The model resolves\n",[42,2099,2100],{"class":44,"line":99},[42,2101,2102],{"class":48},"#    it SILENTLY. Your job: identify every axis and decide explicitly.\n",[42,2104,2105],{"class":44,"line":115},[42,2106,2107],{"class":48},"#    vague:  \"keep it short\"     → the model picks its own definition of \"short\"\n",[42,2109,2110],{"class":44,"line":130},[42,2111,2112],{"class":48},"#    exact:  \"max 3 sentences\"   → checkable, verifiable, no guessing\n",[42,2114,2115],{"class":44,"line":146},[42,2116,62],{"emptyLinePlaceholder":61},[42,2118,2119],{"class":44,"line":161},[42,2120,2121],{"class":48},"# 2. Positive framing beats negative for conceptual constraints.\n",[42,2123,2124],{"class":44,"line":176},[42,2125,2126],{"class":48},"#    \"don't be scary\"  → activates \"scary\" → ironic rebound risk\n",[42,2128,2129],{"class":44,"line":182},[42,2130,2131],{"class":48},"#    \"keep it gentle\"  → no forbidden concept activated → no leak path\n",[42,2133,2134],{"class":44,"line":187},[42,2135,2136],{"class":48},"#    Exception: narrow mechanical negatives (\"no code fences around JSON\") are fine.\n",[42,2138,2139],{"class":44,"line":193},[42,2140,62],{"emptyLinePlaceholder":61},[42,2142,2143],{"class":44,"line":199},[42,2144,2145],{"class":48},"# 3. Quantify everything quantifiable.\n",[42,2147,2148],{"class":44,"line":204},[42,2149,2150],{"class":48},"#    \"brief\" → \"exactly 2 sentences\"\n",[42,2152,2153],{"class":44,"line":214},[42,2154,2155],{"class":48},"#    \"a few\" → \"at most 3\"\n",[42,2157,2158],{"class":44,"line":227},[42,2159,2160],{"class":48},"#    \"appropriate\" → \"scales with complexity: 1-2 sentences for simple, 4-5 for multi-part\"\n",[42,2162,2163],{"class":44,"line":239},[42,2164,62],{"emptyLinePlaceholder":61},[42,2166,2167],{"class":44,"line":251},[42,2168,2169],{"class":48},"# 4. Constraints must be checkable — by you, by an eval (Chapter 19), or by\n",[42,2171,2172],{"class":44,"line":263},[42,2173,2174],{"class":48},"#    downstream code. If you can't write a pass\u002Ffail test for it, it's not\n",[42,2176,2177],{"class":44,"line":275},[42,2178,2179],{"class":48},"#    a constraint, it's a wish.\n",[42,2181,2182],{"class":44,"line":287},[42,2183,62],{"emptyLinePlaceholder":61},[42,2185,2186],{"class":44,"line":292},[42,2187,2188],{"class":48},"# 5. Over-specification ≠ better. The goal is \"no remaining ambiguity on\n",[42,2190,2191],{"class":44,"line":297},[42,2192,2193],{"class":48},"#    axes that matter,\" not \"the longest possible prompt.\" A rigid 15-section\n",[42,2195,2196],{"class":44,"line":303},[42,2197,2198],{"class":48},"#    format spec can cause the model to prioritize format compliance over\n",[42,2200,2201],{"class":44,"line":847},[42,2202,2203],{"class":48},"#    substance, or truncate content to fit the mandated structure.\n",[2205,2206,2207],"style",{},"html pre.shiki code .sdCPZ, html code.shiki .sdCPZ{--shiki-default:#6A737D;--shiki-github-dark:#6A737D}html pre.shiki code .snvgF, html code.shiki .snvgF{--shiki-default:#005CC5;--shiki-github-dark:#79B8FF}html pre.shiki code .svdQ7, html code.shiki .svdQ7{--shiki-default:#D73A49;--shiki-github-dark:#F97583}html pre.shiki code .ssxIu, html code.shiki .ssxIu{--shiki-default:#24292E;--shiki-github-dark:#E1E4E8}html pre.shiki code .sJ6F3, html code.shiki .sJ6F3{--shiki-default:#032F62;--shiki-github-dark:#9ECBFF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .github-dark .shiki span {color: var(--shiki-github-dark);background: var(--shiki-github-dark-bg);font-style: var(--shiki-github-dark-font-style);font-weight: var(--shiki-github-dark-font-weight);text-decoration: var(--shiki-github-dark-text-decoration);}html.github-dark .shiki span {color: var(--shiki-github-dark);background: var(--shiki-github-dark-bg);font-style: var(--shiki-github-dark-font-style);font-weight: var(--shiki-github-dark-font-weight);text-decoration: var(--shiki-github-dark-text-decoration);}html pre.shiki code .sIsaT, html code.shiki .sIsaT{--shiki-default:#6F42C1;--shiki-github-dark:#B392F0}html pre.shiki code .svAP2, html code.shiki .svAP2{--shiki-default:#032F62;--shiki-github-dark:#DBEDFF}",{"title":37,"searchDepth":52,"depth":52,"links":2209},[2210,2211,2212,2213,2214,2215,2216,2217,2218],{"id":16,"depth":52,"text":17},{"id":309,"depth":52,"text":310},{"id":432,"depth":52,"text":433},{"id":1449,"depth":52,"text":1450},{"id":1691,"depth":52,"text":1692},{"id":1738,"depth":52,"text":1739},{"id":1866,"depth":52,"text":1867},{"id":2019,"depth":52,"text":2020},{"id":2066,"depth":52,"text":2067},"The highest-leverage prompt engineering skill — eliminating ambiguity through explicit, checkable constraints. Production patterns for positive framing, quantitative boundaries, and anti-rebound instruction design. Code-first reference for mid-to-senior engineers.","md",{},"\u002Fprompt-engineering\u002F04-clarity-and-specificity",{"title":5,"description":2219},"prompt-engineering\u002F04-clarity-and-specificity","OqQZJ1o13IgyBm7z9rcCRzbJrS7Uaz2jS6464ewKTGs",1789924650813]