Prompt Engineering & Structured Output

Vague instructions leave the model to guess your bar, producing inconsistent, noisy output. A precise, testable rule gives it a clear line to apply the same way every time.

مبہم ہدایات ماڈل کو آپ کا معیار اندازے پر چھوڑ دیتی ہیں، جس سے غیر یکساں، شور والا نتیجہ آتا ہے۔ ایک صاف، جانچنے لائق اصول اسے واضح لکیر دیتا ہے جسے وہ ہر بار ایک جیسا لگائے۔

Confidence-based hedging doesn't tell the model WHAT counts as a real issue. Categorical criteria (report X, skip Y) actually move precision.

confidence پر ٹال مٹول ماڈل کو یہ نہیں بتاتی کہ اصل مسئلہ کیا ہے۔ دو ٹوک اصول (X رپورٹ کرو، Y چھوڑ دو) اصل میں درستگی بڑھاتے ہیں۔

If one finding-type is noisy, developers start ignoring ALL findings, including the good ones. You may temporarily disable a noisy category to protect overall trust while you fix its prompt.

اگر ایک قسم کے نتائج شور والے ہوں تو ڈیولپر سارے نتائج نظر انداز کرنے لگتے ہیں، اچھے بھی۔ آپ اس شور والی قسم کو وقتی طور پر بند کر سکتے ہیں تاکہ اس کا پرامپٹ ٹھیک کرتے ہوئے مجموعی بھروسہ بچا رہے۔

Reporting criteria decide RELEVANCE (does this belong in the review?); confidence only estimates certainty. Claude can be highly confident about a trivial naming nit yet unsure about a subtle security flaw — so scope, not confidence, is what keeps noise out. Bake the report/skip lists into the system prompt and the output schema.

رپورٹنگ کے اصول یہ طے کرتے ہیں کہ بات متعلقہ ہے یا نہیں (کیا یہ جائزے میں آنی چاہیے؟)؛ confidence صرف یقین کا اندازہ ہے۔ Claude کسی معمولی نام کی بات پر بہت پُریقین اور کسی باریک سیکیورٹی خامی پر غیر یقینی ہو سکتا ہے — اس لیے شور دائرہ روکتا ہے، confidence نہیں۔ رپورٹ/چھوڑ کی فہرستیں سسٹم پرامپٹ اور آؤٹ پٹ schema میں ڈالیں۔

Report: security holes, incorrect logic, runtime failures, data-loss risks,
        broken authorization, serious performance regressions.
Skip:   formatting, naming preferences, existing repo conventions,
        subjective refactors, anything a linter already catches.

Controlled degradation: keep the reliable categories running and mute only the noisy one — a single 60%-wrong category makes developers ignore ALL findings (alert fatigue), so the good findings die with the bad. Re-enable only after re-evaluation shows precision recovered.

قابو میں کمی: بھروسے مند اقسام چالو رکھیں اور صرف شور والی بند کریں — ایک ۶۰٪ غلط قسم ڈیولپر کو سارے نتائج نظر انداز کرا دیتی ہے (الرٹ سے تھکن)، تو اچھے نتائج بھی بروں کے ساتھ مر جاتے ہیں۔ دوبارہ صرف تب چالو کریں جب نئی جانچ درستگی کی بحالی دکھائے۔

Definitions state the rule; examples teach the boundary so the same authz bug isn't 'critical' in one review and 'medium' in the next. This is valid few-shot use — Claude is learning a classification line, not inventing missing facts. Severity then drives workflow: Critical → block merge, High → require review, Medium → review queue, Low → optional suggestion.

تعریفیں اصول بتاتی ہیں؛ مثالیں حد سکھاتی ہیں تاکہ وہی authz خامی ایک جائزے میں 'critical' اور اگلے میں 'medium' نہ ہو۔ یہ few-shot کا درست استعمال ہے — Claude درجہ بندی کی لکیر سیکھ رہا ہے، غائب حقائق گھڑ نہیں رہا۔ پھر شدت کام چلاتی ہے: Critical ← merge روکو، High ← جائزہ لازم، Medium ← جائزہ قطار، Low ← اختیاری مشورہ۔

Critical — full compromise / irreversible data loss:
    eval(user_supplied_code)
High — authz bypass or core-function failure:
    if user.is_admin: deny_access()   # allow/deny branches reversed
Medium — recoverable, limited scope:
    try: process_payment()
    except Exception: pass            # swallows the failure
Low — maintainability / minor inefficiency:
    if item in very_large_list: ...   # O(n) membership inside a loop

When you've written thorough instructions and output still varies, 2–4 worked examples showing the exact format and reasoning are the highest-impact next step.

جب آپ تفصیلی ہدایات لکھ چکے ہوں اور آؤٹ پٹ پھر بھی بدلتا رہے، تو ۲-۴ حل شدہ مثالیں جو عین شکل اور سوچ دکھائیں، سب سے زیادہ اثر والا اگلا قدم ہیں۔

Examples are especially powerful for edge/ambiguous cases: show the model a hard case and the correct handling, and it generalizes the judgment.

مثالیں خاص/مبہم صورتوں کے لیے خاص طور پر طاقتور ہیں: ماڈل کو ایک مشکل صورت اور اس کا درست حل دکھائیں، تو وہ اس فیصلے کو نئے معاملوں پر بھی لگا لیتا ہے۔

Good examples teach a principle, so the model handles new inputs it hasn't seen — not just the literal examples.

اچھی مثالیں ایک اصول سکھاتی ہیں، تاکہ ماڈل ان نئے ان پٹ کو بھی سنبھالے جو اس نے نہیں دیکھے — صرف انہی مثالوں تک محدود نہیں۔

Showing correct extraction from messy, varied documents curbs the model's tendency to invent values when a format is unfamiliar.

بے ترتیب، مختلف دستاویزوں سے درست نکالنا دکھانا ماڈل کی اُس عادت کو روکتا ہے کہ اجنبی فارمیٹ پر قدریں گھڑ لے۔

Include the reasoning, not just the answer — 'chose lookup_order because the query names a specific order #, not a person'.

صرف جواب نہیں، وجہ بھی شامل کریں — 'lookup_order اس لیے چنا کہ سوال کسی خاص آرڈر نمبر کا نام لیتا ہے، کسی شخص کا نہیں'۔

Query: "what's the status of #12345?"
  -> lookup_order  (names a specific order #, not a person)
Query: "find orders for jane@x.com"
  -> get_customer FIRST  (need the customer before their orders)
// show the REASONING, not just the chosen tool

Don't describe the format — show one fully-worked finding with every field populated. The model then mirrors that shape, so output stays parseable and consistent across runs.

فارمیٹ بیان نہ کریں — ایک مکمل حل شدہ نتیجہ دکھائیں جس کا ہر خانہ بھرا ہو۔ پھر ماڈل وہی شکل نقل کرتا ہے، تاکہ آؤٹ پٹ چکروں میں پڑھنے لائق اور یکساں رہے۔

location: auth/login.py:42
issue: password compared with == (timing-safe compare needed)
severity: high
fix: use hmac.compare_digest(a, b)

Pair a 'this is fine, don't flag it' example with a 'this is a real bug, flag it' example. The contrast teaches the boundary so the model generalizes it to new code instead of flagging everything that looks similar.

ایک 'یہ ٹھیک ہے، نشان نہ لگاؤ' مثال کو ایک 'یہ اصل خرابی ہے، نشان لگاؤ' مثال کے ساتھ رکھیں۔ یہ فرق حد سکھاتا ہے تاکہ ماڈل اسے نئے کوڈ پر لگائے، ہر ملتی جلتی چیز پر نشان لگانے کے بجائے۔

FINE (don't flag):
    digest = hashlib.sha256(pw + salt).hexdigest()   # salted hash - ok
BUG (flag):
    if password == stored: ...   # plaintext compare + timing leak
// the contrast teaches the boundary so the model generalizes it

Extraction breaks on formats the model hasn't seen. Include examples spanning the structural variety of real inputs — and explicitly show a missing field mapping to null — so it handles messy documents without inventing values.

نکالنا اُن فارمیٹس پر ٹوٹتا ہے جو ماڈل نے نہیں دیکھے۔ ایسی مثالیں شامل کریں جو اصل ان پٹ کی بناوٹی مختلف اقسام کو ڈھانپیں — اور صاف دکھائیں کہ غائب خانہ null بنتا ہے — تاکہ وہ بے ترتیب دستاویز بغیر قدریں گھڑے سنبھالے۔

Example A (inline):       "...growth [Smith 2024]..." -> { claim, source }
Example B (bibliography): "[1] Smith, J. (2024)"       -> { claim, source }
Example C (no date):      date absent                  -> "date": null
// span the real variety; show null explicitly so it won't invent a date

Defining an extraction 'tool' whose input is your JSON schema forces the model to emit data in that exact shape via a tool_use block. No stray prose, no malformed JSON — the syntax is guaranteed.

ایک نکالنے والا 'ٹول' بنانا جس کا ان پٹ آپ کا JSON schema ہو، ماڈل کو مجبور کرتا ہے کہ وہ ڈیٹا اسی عین شکل میں tool_use بلاک سے دے۔ نہ فالتو عبارت، نہ خراب JSON — بناوٹ کی ضمانت ہو جاتی ہے۔

tools=[{ 'name':'extract_invoice',
  'input_schema': { 'type':'object',
    'properties': { 'total': {'type':'number'},
                    'vendor': {'type':['string','null']} },
    'required': ['total'] } }]
# read the structured data from resp tool_use.input

For guaranteed extraction, don't leave it on auto (the model might answer in prose). Use any when the doc type is unknown among several schemas, or force a specific extraction tool.

یقینی نکالنے کے لیے اسے auto پر نہ چھوڑیں (ماڈل عبارت میں جواب دے سکتا ہے)۔ جب دستاویز کی قسم کئی schemas میں سے پتا نہ ہو تو any استعمال کریں، یا کسی خاص نکالنے والے ٹول کو مجبور کریں۔

A schema guarantees shape, not correctness. The model can still put a value in the wrong field or return line items that don't add up to the total. Catch those with semantic validation (Task 4.4).

schema شکل کی ضمانت دیتا ہے، درستی کی نہیں۔ ماڈل پھر بھی قدر غلط خانے میں ڈال سکتا ہے یا ایسی رقمیں دے سکتا ہے جن کا جوڑ کل سے نہ ملے۔ انہیں مطلب کی جانچ سے پکڑیں (Task 4.4)۔

Mark fields optional/nullable when the source may lack them. For categories that won't be exhaustive, add an other enum value plus a free-text detail field so new cases have somewhere to go.

جب ذریعے میں خانے نہ ہوں تو انہیں optional/nullable رکھیں۔ جن اقسام کی فہرست مکمل نہ ہو، ان کے لیے ایک other enum قدر اور آزاد متن کا خانہ رکھیں تاکہ نئے معاملوں کے لیے جگہ ہو۔

Model your target shape as a tool whose input_schema IS the schema, then read the structured data straight off the tool_use block. This is the most reliable way to get valid JSON — the syntax is guaranteed by construction.

اپنی مطلوبہ شکل کو ایسے ٹول کے طور پر بنائیں جس کا input_schema ہی وہ schema ہو، پھر منظم ڈیٹا سیدھا tool_use بلاک سے پڑھیں۔ درست JSON پانے کا یہ سب سے بھروسے مند طریقہ ہے — بناوٹ کی ضمانت خود ساخت سے آتی ہے۔

tools=[{ 'name':'extract_invoice',
  'input_schema': { 'type':'object',
    'properties': { 'total': {'type':'number'} },
    'required': ['total'] } }]
data = resp.tool_use.input   # already-parsed, schema-shaped

When you offer several extraction schemas and don't know which fits, any forces the model to pick and call one instead of replying in prose — so you always get structured output, whichever schema matches.

جب آپ کئی نکالنے والے schemas پیش کریں اور پتا نہ ہو کون سا فٹ ہے، تو any ماڈل کو مجبور کرتا ہے کہ عبارت میں جواب دینے کے بجائے کوئی ایک چنے اور چلائے — تاکہ ہمیشہ منظم آؤٹ پٹ ملے، جو بھی schema ملے۔

tools = [extract_invoice, extract_receipt, extract_contract]
tool_choice = { 'type': 'any' }   # model MUST pick and call ONE
// unknown doc type -> guaranteed structured output;
// 'auto' could reply in prose instead

Forcing a named tool guarantees a required first step (metadata extraction) happens before dependent work, rather than hoping the model chooses it. Do enrichment in follow-up turns once that output exists.

کسی نامی ٹول کو مجبور کرنا یقینی بناتا ہے کہ ایک ضروری پہلا قدم (metadata نکالنا) منحصر کام سے پہلے ہو، بجائے اس کے کہ ماڈل کے چننے کی امید رکھیں۔ باقی افزائش (enrichment) اگلی باریوں میں کریں جب وہ نتیجہ موجود ہو۔

# turn 1: force the required first step
tool_choice = { 'type': 'tool', 'name': 'extract_metadata' }
# turn 2 (once metadata exists): let dependent work run
tool_choice = { 'type': 'auto' }

A required field on data that isn't in the document pressures the model to invent a value. Nullable fields let it correctly return null.

جو ڈیٹا دستاویز میں نہیں، اس پر required خانہ ماڈل کو قدر گھڑنے پر مجبور کرتا ہے۔ nullable خانے اسے درست null دینے دیتے ہیں۔

// BAD: required field on data the doc may not contain
"required": ["total", "po_number"]     // -> model invents a po_number
// GOOD: nullable so absence is representable
"po_number": { "type": ["string", "null"] },
"required": ["total"]

For categories that can't be exhaustive, give the model escape hatches: an unclear/other enum plus a free-text detail field so novel cases land somewhere valid instead of being force-fit. Pair the schema with explicit normalization rules (dates, currency) so shape AND format are consistent.

جن اقسام کی فہرست مکمل نہ ہو، ماڈل کو نکلنے کے راستے دیں: ایک unclear/other enum اور آزاد متن کا خانہ تاکہ نئے معاملے زبردستی ٹھونسے جانے کے بجائے کسی درست جگہ آ جائیں۔ schema کے ساتھ صاف معیار بندی کے اصول رکھیں (تاریخیں، کرنسی) تاکہ شکل اور فارمیٹ دونوں یکساں ہوں۔

"category": { "enum": ["invoice", "receipt", "other"] },
"category_detail": { "type": ["string", "null"] }   // used when 'other'

On a validation failure, send a follow-up that includes the original document, the failed extraction, and the exact error. The model self-corrects far better with the specific error than with a generic 'try again'.

جانچ ناکام ہونے پر ایک follow-up بھیجیں جس میں اصل دستاویز، ناکام نتیجہ، اور عین خرابی ہو۔ ماڈل عام 'دوبارہ کوشش کرو' کے مقابلے مخصوص خرابی کے ساتھ کہیں بہتر خود کو درست کرتا ہے۔

retry_prompt = f"""Your extraction failed validation.
Document: {doc}
Your output: {failed}
Error: line_items sum to 90.00 but total is 100.00.
Fix and re-extract."""

If the required value isn't in the document at all, no amount of retrying will conjure it. Retries fix FORMAT/STRUCTURE problems, not missing-data problems.

اگر مطلوبہ قدر دستاویز میں ہے ہی نہیں، تو کتنی بھی دوبارہ کوشش اسے پیدا نہیں کرے گی۔ دوبارہ کوشش شکل/بناوٹ کے مسئلے ٹھیک کرتی ہے، غائب ڈیٹا کے نہیں۔

Recording which code construct triggered each finding lets you later analyze which patterns produce false positives when developers dismiss them.

یہ ریکارڈ کرنا کہ ہر نتیجہ کس کوڈ ساخت سے آیا، بعد میں تجزیہ کرنے دیتا ہے کہ کون سے انداز جھوٹے الارم بناتے ہیں جب ڈیولپر انہیں رد کرتے ہیں۔

Syntax is handled by tool_use schemas. Semantic checks are your job: compare a calculated_total to a stated_total, flag conflicts.

بناوٹ کو tool_use schemas سنبھالتے ہیں۔ مطلب کی جانچ آپ کا کام ہے: calculated_total کو stated_total سے ملائیں، فرق کی نشاندہی کریں۔

Give the retry everything it needs to self-correct: the original source, its own failed output, and the EXACT error (not 'try again'). Concrete error text lets the model target the fix instead of guessing what went wrong.

دوبارہ کوشش کو خود کو درست کرنے کے لیے سب کچھ دیں: اصل ذریعہ، اس کا اپنا ناکام آؤٹ پٹ، اور عین خرابی (نہ کہ 'دوبارہ کوشش کرو')۔ ٹھوس خرابی کا متن ماڈل کو یہ اندازہ لگانے کے بجائے کہ کیا غلط ہوا، سیدھا حل کا نشانہ لینے دیتا ہے۔

retry = f"Your extraction failed validation.\nDocument: {doc}\n" \
        f"Your output: {failed}\nError: line_items sum to 90.00 but total is 100.00.\nFix and re-extract."

Retries fix HOW data was returned (wrong shape, wrong field), never WHETHER it exists. If the value simply isn't in the source, stop retrying — you'll just burn calls; return null or flag it missing instead.

دوبارہ کوشش یہ ٹھیک کرتی ہے کہ ڈیٹا کیسے آیا (غلط شکل، غلط خانہ)، یہ کبھی نہیں کہ وہ موجود ہے یا نہیں۔ اگر قدر ذریعے میں ہے ہی نہیں تو کوشش روک دیں — صرف کالیں ضائع ہوں گی؛ اس کے بجائے null دیں یا غائب نشان زد کریں۔

Error: "total malformed: '$1,00.0'"     -> RETRY (format problem, fixable)
Error: "po_number not found in document" -> STOP retrying (data is absent)
   -> return { "po_number": null } or flag it missing
// retrying absent data just burns calls

Tag each finding with the code construct that triggered it. When developers dismiss findings, you can then aggregate by pattern and see which constructs are noisy — data that tells you which category to tune or disable.

ہر نتیجے پر اس کوڈ ساخت کا نشان لگائیں جس سے وہ آیا۔ جب ڈیولپر نتائج رد کریں، تو آپ انداز کے حساب سے جوڑ کر دیکھ سکتے ہیں کون سی ساختیں شور والی ہیں — وہ ڈیٹا جو بتاتا ہے کون سی قسم سدھارنی یا بند کرنی ہے۔

{ "issue": "possible race condition",
  "detected_pattern": "check-then-act on shared dict" }
// aggregate dismissed findings by detected_pattern:
// "check-then-act" is 60% false positive -> tune or disable that category

Have the model emit both the value it computed and the value the document states, then compare them in code. A conflict_detected flag surfaces semantic errors (bad sums) that a schema can never catch.

ماڈل سے وہ قدر بھی نکلوائیں جو اس نے حساب کی اور وہ بھی جو دستاویز میں لکھی ہے، پھر کوڈ میں انہیں ملائیں۔ ایک conflict_detected نشان مطلب کی خرابیاں (غلط جوڑ) سامنے لاتا ہے جو schema کبھی نہیں پکڑ سکتا۔

{ "stated_total": 100.00,
  "calculated_total": 90.00,
  "conflict_detected": true }

The Batch API halves cost in exchange for asynchronous processing (up to 24 hours, no latency guarantee). Perfect for work that can wait; unacceptable for anything a person is blocked on.

Batch API قیمت آدھی کر دیتا ہے مگر بدلے میں async پروسیسنگ (۲۴ گھنٹے تک، وقت کی کوئی ضمانت نہیں)۔ انتظار کر سکنے والے کام کے لیے بہترین؛ جہاں کوئی شخص رُکا ہو وہاں ناقابلِ قبول۔

You can't run tools mid-request and feed results back within one batch item. If your task needs an agentic tool loop, batch isn't the right fit.

آپ ایک batch آئٹم کے اندر بیچ میں ٹول چلا کر نتائج واپس نہیں دے سکتے۔ اگر آپ کے کام کو ایجنٹ والا ٹول لوپ چاہیے تو batch صحیح انتخاب نہیں۔

Each batch item carries a custom_id you set, so you can match responses back to inputs regardless of ordering — and resubmit only the ones that failed.

ہر batch آئٹم پر آپ کا رکھا custom_id ہوتا ہے، تاکہ آپ ترتیب سے قطع نظر جوابوں کو ان پٹ سے ملا سکیں — اور صرف ناکام آئٹم دوبارہ بھیجیں۔

If a human or a merge is blocked waiting, use the synchronous API — the Batch API's 24h window and lack of latency SLA make 'often faster' a trap. Reserve batch (50% cheaper) for work that can wait: nightly reports, weekly audits, bulk test-gen.

اگر کوئی انسان یا merge انتظار میں رُکا ہو تو synchronous API استعمال کریں — Batch API کی ۲۴ گھنٹے کی مہلت اور وقت کی ضمانت نہ ہونا 'اکثر تیز' کو دھوکا بنا دیتا ہے۔ batch (آدھی قیمت) انتظار کر سکنے والے کام کے لیے رکھیں: رات کی رپورٹیں، ہفتہ وار جائزے، بڑی تعداد میں ٹیسٹ بنانا۔

Blocking pre-merge check (dev is waiting)    -> Synchronous API
Nightly report / weekly audit / bulk test-gen -> Batch API (50% cheaper)
// Batch has NO latency SLA (up to 24h) -> "often faster" is a trap here

If processing can take 24h and your SLA is 30h, submitting every ≤4h keeps the worst case (wait + process) within 30h.

اگر پروسیسنگ ۲۴ گھنٹے تک لے سکتی ہے اور آپ کا وعدہ (SLA) ۳۰ گھنٹے ہے، تو ہر ۴ گھنٹے یا اس سے پہلے بھیجتے رہنا بدترین صورت (انتظار + پروسیسنگ) کو بھی ۳۰ گھنٹے کے اندر رکھتا ہے۔

processing worst-case = 24h,  SLA = 30h
-> submit every <= 4h    (4h max wait + 24h processing = 28h < 30h)
// batching once/day risks 24h wait + 24h processing = 48h -> blows the SLA

Because each item carries your custom_id, you can identify exactly which ones failed and resubmit only those — after fixing the cause, e.g. splitting a document that exceeded the size limit — instead of rerunning the whole batch.

چونکہ ہر آئٹم پر آپ کا custom_id ہوتا ہے، آپ ٹھیک پہچان سکتے ہیں کون سے ناکام ہوئے اور صرف انہی کو دوبارہ بھیج سکتے ہیں — وجہ ٹھیک کر کے، مثلاً حد سے بڑی دستاویز کو ٹکڑوں میں بانٹ کر — پورا batch دوبارہ چلانے کے بجائے۔

results = poll_batch()
failed = [r.custom_id for r in results if r.error]   # e.g. oversized docs
for cid in failed:
    resubmit(chunk(doc[cid]))    # fix the cause, resend ONLY those
// don't rerun the whole batch

A prompt flaw multiplies across thousands of batch items and you won't see it for hours. Validate on a small sample first so the large run lands a high first-pass success rate instead of returning a mountain of failures.

پرامپٹ کی ایک خامی ہزاروں batch آئٹمز میں پھیل جاتی ہے اور آپ کو گھنٹوں پتا نہیں چلتا۔ پہلے ایک چھوٹے نمونے پر جانچیں تاکہ بڑا چکر پہلی بار میں اونچی کامیابی دے، ناکامیوں کا پہاڑ نہ لوٹائے۔

sample = docs[:50]
run_sync(sample); measure_first_pass_success()   # tune the prompt HERE
# only then submit the 10,000-doc batch
// a prompt flaw multiplies across the full run - and you won't see it for hours

The instance that wrote the code has already 'convinced itself'. Asking it to review its own work (even with extended thinking) catches less than a fresh set of eyes.

جس instance نے کوڈ لکھا وہ خود کو 'قائل' کر چکا ہے۔ اس سے اپنے کام کا جائزہ لینے کو کہنا (چاہے گہری سوچ کے ساتھ) تازہ نظروں کے مقابلے کم پکڑتا ہے۔

One pass over many files gives uneven, sometimes contradictory feedback. Per-file passes ensure consistent depth; a separate integration pass handles cross-file data flow.

کئی فائلوں پر ایک ہی چکر غیر یکساں، کبھی متضاد رائے دیتا ہے۔ ہر فائل کے الگ چکر یکساں گہرائی یقینی بناتے ہیں؛ اور ایک الگ انضمام چکر فائلوں کے درمیان ڈیٹا کا بہاؤ سنبھالتا ہے۔

The instance that wrote the code has already convinced itself it's correct. A fresh instance with no prior reasoning context questions assumptions the author-instance rationalizes away — beating both self-review and extended thinking.

جس instance نے کوڈ لکھا وہ خود کو قائل کر چکا کہ درست ہے۔ ایک تازہ instance جس کے پاس پہلے کی سوچ نہیں، اُن مفروضوں پر سوال اٹھاتا ہے جنہیں لکھنے والا صفائیاں دے کر ٹال دیتا ہے — یہ خود جائزے اور گہری سوچ دونوں سے بہتر ہے۔

gen_session    -> writes the code (already 'convinced itself')
review_session -> NEW instance, no prior context, reviews it
// fresh eyes question assumptions the author-instance rationalizes away;
// beats self-review AND extended thinking

One pass across many files gives uneven, sometimes contradictory feedback (attention dilution). Per-file passes deliver consistent depth; a dedicated integration pass catches data-flow issues that only appear across files. A bigger context window does NOT fix this.

کئی فائلوں پر ایک ہی چکر غیر یکساں، کبھی متضاد رائے دیتا ہے (توجہ بٹنا)۔ ہر فائل کے الگ چکر یکساں گہرائی دیتے ہیں؛ ایک الگ انضمام چکر وہ ڈیٹا بہاؤ کے مسئلے پکڑتا ہے جو صرف فائلوں کے درمیان ظاہر ہوتے ہیں۔ بڑا context window اسے ٹھیک نہیں کرتا۔

for f in changed_files:            # per-file pass: consistent depth
    review(f)
review_integration(changed_files)  # separate pass: cross-file data flow
// one pass over many files -> uneven, contradictory feedback

A verification pass can attach a confidence signal used to ROUTE — auto-accept high-confidence findings, send borderline ones to a human. Note confidence gates routing, not scope (which categorical report/skip criteria decide, per Task 4.1).

ایک تصدیقی چکر ایک confidence اشارہ لگا سکتا ہے جو راستہ طے کرتا ہے — زیادہ اعتماد والے نتائج خودبخود قبول، سرحدی والے انسان کو۔ یاد رہے confidence راستہ (routing) طے کرتا ہے، دائرہ نہیں (دائرہ دو ٹوک رپورٹ/چھوڑ اصول طے کرتے ہیں، Task 4.1)۔

if finding.confidence >= 0.85: auto_report(finding)
else:                        queue_for_human(finding)