Agentsop Signature Design

Signature-Design — Promote Prose → Typed Contract

"DSPy uses the field names as the only natural-language hint the optimizer has about intent before it sees data. Name them like you'd name function parameters in well-written code." — derived from [dspy.ai/learn/programming/signatures/], see references/R1-source-evidence.md

This skill is the decision layer, not the library layer. It tells you when a prose prompt has become "load-bearing" enough to deserve a typed Signature, and how to shape its fields. For the actual API (dspy.Signature, InputField, OutputField, Predict, ChainOfThought, compile, save) defer to the [[dspy]] skill; for the full program→evaluate→optimize SOP defer to [[agentsop-dspy]].

1. 何时激活 (When to activate)

Activate this overlay the moment a hand-written prompt crosses any one of three load-bearing thresholds.

Secondary signals (each strengthens, none alone is sufficient):

• The prompt is about to be model-swapped (GPT → Llama) and you fear it will break — Signatures + recompile is the documented fix (R1, claim S6; see [[agentsop-dspy]] Case B).
• A metric already exists for this task — you are one step from optimization, and optimizers require a Signature.
• The prompt mixes task instruction + few-shot demos + format spec in one blob — Signatures separate these cleanly.

Do NOT activate when:

• The prompt is one-shot ("summarize this one email") — keep it as a raw string; the contract has no second reader.
• The task signature is still changing daily — promoting now just churns boilerplate. Wait for the I/O to stabilize (R1, claim S7).
• The question is HOW to write the Signature class / pick a module / compile — that is the [[dspy]] skill's job, not this rubric's.
• Output must be free-form human prose with no downstream parsing and no reuse — a Signature buys nothing.

2. 核心心智模型 (Core mental model)

A Signature is a typed function contract for a single LM call. Promote a prose prompt to a Signature exactly when the prompt becomes load-bearing — when something other than a one-time human reader depends on its shape.

Think of the progression as the same lifecycle a script goes through when it earns a function:

prose prompt string          →   typed Signature
─────────────────────────        ─────────────────────────
"You are an expert... given     class Classify(dspy.Signature):
 the ticket below, output           """Route a support ticket."""
 the category and a one-line        ticket: str  = dspy.InputField()
 reason. Categories are..."         category: Literal[...] = dspy.OutputField()
                                     reason: str  = dspy.OutputField(desc="<=15 words")
inline narration of I/O          explicit, named, typed I/O
human reads / eyeballs           code parses category, logs reason
each caller copies the blob      one contract, N callers import it
optimizer sees nothing           optimizer rewrites instructions, keeps field names

Three load-bearing ideas (all sourced; see references/R1-source-evidence.md):

1. Field names are the contract. Before the optimizer ever sees data, the only intent signal it has is the field names. question -> answer ≠ query -> response. Name fields like function parameters in clean code (R1, claim S2). This is the reason promotion is worth it: you convert narration into a machine-readable intent signal.

2. The Signature shape is YOUR code; the prompt text is the optimizer's. When you compile, the optimizer rewrites instructions and demos — but it never changes field names, field count, or types (R1, claim S5). So the Signature is the stable seam between "what I own" and "what the compiler owns." A prose prompt has no such seam — everything is tangled.

3. Promote on load-bearing, not on aspiration. A Signature you optimize a 5-line one-shot prompt into is pure overhead. The payoff appears only when the prompt is long, code-consumed, or reused. Below that line, raw prompting wins (R1, claims S7, S1).

The PyTorch analogy from [[agentsop-dspy]] holds: a Signature ≈ a forward() shape contract. You don't write a nn.Module for a one-line lambda; you write one when the shape is reused and trained.

3. SOP 工作流 (The promotion SOP)

A four-step gate. Run it top-to-bottom; each step has an exit criterion. Implementation of any step lives in the [[dspy]] skill — this SOP only tells you what decision to make at each step.

Step 0 — Gate: is this prompt load-bearing?

Run the §1 trigger table. If zero triggers fire → stop, keep the prose prompt. Promotion is overhead. Exit: at least one of {>50 lines, code-consumed output, reused} is true.

Step 1 — Identify inputs and outputs

Read the prose prompt and extract every variable thing the LM is given (inputs) and every distinct thing it must return (outputs). A common smell: the prose says "output the category and a confidence and a reason" — that is three output fields, not one paragraph to regex later. Exit: you can list inputs and outputs as a flat set of named slots, each with a Python type.

Step 2 — Name fields semantically

Rename each slot to read like a function parameter. text → ticket, out → category, resp → reason. The name carries the optimizer's only pre-data intent signal (R1, claim S2). Avoid generic input/output. Exit: every field name would be self-explanatory to a teammate reading only the field list.

Step 3 — Add descriptions only where the name underspecifies

Add InputField(desc=...) / OutputField(desc=...) only when the field name alone is ambiguous or the value needs a constraint the name can't carry (format, length, units, allowed values). The DSPy cheatsheet's own example adds a desc on output (answer, desc="often between 1 and 5 words") but leaves the input bare (R1, claim S3). Over-describing every field bloats the prompt and fights the optimizer. Exit: descriptions exist for exactly the fields that need disambiguation, and no others.

Step 4 — Hand off module choice to [[dspy]]

Picking Predict vs ChainOfThought vs ReAct, then evaluating and compiling, is out of scope for this decision skill — that is the [[dspy]] skill (modules) and [[agentsop-dspy]] (Stage 1–3 workflow). Your deliverable from this skill is a well-shaped Signature, handed to those skills. Exit: Signature is named, typed, minimally described, and committed; you have switched contexts to [[dspy]].

When to iterate back

If, after compiling (in [[dspy]]), the optimizer plateaus, the most common root cause is an ambiguous Signature — not a bad optimizer (R1, claim S8). Loop back to Step 1: are inputs/outputs really separated? Are field names carrying intent?

4. 操作模型 (Operations — Trigger / Action / Output / Evidence)

Eight operations. The first two are the gate; the rest are the shaping rubric. Full Trigger/Action/Output/Evidence records are in intermediate/operation_candidates.json.

4.1 Promote-trigger checklist (the gate)

Promote prose → Signature when you can check ≥1 box. Each box maps to a §1 trigger:

[ ] LENGTH      prompt string > ~50 lines
[ ] CONSUMED    LM output is parsed / branched on / stored by code (not just human-read)
[ ] REUSED      same prompt called from > 1 site, or inside a loop
[ ] (bonus) about to model-swap, OR a metric already exists, OR blob mixes instruction+demos+format

Zero boxes → do not promote. One box → promote. (Source: §1 triggers; R1 S1, S6, S7.)

4.2 Operation table

4.3 Field-naming rules (the heart of this skill)

1. Name like a function parameter, not like a prompt. customer_email, not the text the user pasted.
2. Inputs are nouns the LM receives; outputs are nouns the LM produces. Don't smuggle an output into an input name.
3. One concept per field. "category_and_reason" is two fields. Split it (OP-2).
4. Prefer the most specific type the value can hold. Literal["bug","billing","other"] over str when the set is closed (OP-5) — the type is documentation and a parse guard.
5. Reserve desc= for what the name can't say: format, length, units, allowed values, edge-case handling.

4.4 When InputField vs OutputField descriptions matter

Rule of thumb: input descs prevent confusion; output descs prevent malformed values. Default to fewer descs; add one only when you can name the specific failure it prevents.

5. 困境决策案例 (Dilemma cases)

Case A — "The 80-line mega-prompt: promote whole, or split first?"

困境: A support-triage prompt is 80 lines: persona + 4 categories with examples + output-format spec + edge-case rules. The output ("category, confidence, escalate?") is parsed by routing code. Promote it verbatim into one Signature, or restructure first?

约束:

• Output is code-consumed (routing branches on category and escalate) → §1 CONSUMED trigger fires.
• The 80 lines mix instruction + demos + format → the optimizer should own most of that text, not you.
• Three distinct return values are currently scraped from one free-text blob.

决策步骤:

1. Promote — the gate is satisfied (CONSUMED + LENGTH). This is exactly the load-bearing case (R1 S1).
2. Do NOT copy the 80 lines into one giant docstring. Inputs = ticket: str. Outputs = category: Literal[...], confidence: float, escalate: bool (OP-2, OP-5). The four category descriptions and examples are demos/instructions the optimizer will own — drop them from your code (mental model #2, R1 S5).
3. Type the outputs so the router stops regex-scraping (OP-5). escalate: bool replaces parsing the word "yes" out of prose.
4. Add a desc only on confidence ("0–1, calibrated") since the name underspecifies the range (OP-4, §4.4).
5. Hand to [[dspy]] to pick ChainOfThought (reasoning helps category choice) and to compile against the existing routing-accuracy metric.

结果: An 80-line blob collapses to a 5-field typed contract; the router drops all string-scraping; the prose that was the prompt becomes optimizer-owned instructions/demos.

可提取的操作: When promoting a mega-prompt, keep only the I/O shape in code; let the instruction/demo prose become the optimizer's territory. Split fused outputs; type closed-set and boolean outputs.