/agentsop-signature-design

name: agentsop-signature-design
version: 0.1.0
description: >-
  Decision rubric for promoting a prose prompt into a typed DSPy Signature. This is an
  ENHANCE overlay on top of the [[dspy]] library skill: it does NOT teach DSPy syntax — it
  answers the coder-agent decision "when do I stop hand-writing a prompt string and declare
  it as a `dspy.Signature`, and how do I name/describe its fields so the optimizer and the
  calling code both get a clean contract." Activate when: a prompt string grows past ~50
  lines; the LM output is consumed by code (parsed, branched on, stored) rather than read by
  a human; the same prompt is reused across >1 call site; or a teammate asks "should this be
  a Signature?". Do NOT activate for one-shot throwaway prompts, or for HOW-TO questions
  about DSPy modules /optimizers/compile — defer those to the [[dspy]] skill and the
  [[agentsop-dspy]] workflow skill. Search keywords: typed prompt, structured prompt, DSPy
  Signature, prompt as a function, prompt contract, when to formalize a prompt.

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.

| Trigger | Concrete signal | Why it matters | |---|---|---| | **Length** | A single prompt string grows past **~50 lines** of f-string / template | Long prose prompts hide their I/O contract inside narration; the [[agentsop-dspy]] skill names this exact symptom: "hand-written prompts grow past ~50 lines; brittleness on model swap" (`R1`, claim S1) | | **Code-consumed output** | The LM response is **parsed, branched on, or stored** by downstream code (not just shown to a human) | If code reads the output, the output has a *type*. An untyped prompt forces brittle regex/JSON-scraping at every call site | | **Reuse** | The same prompt (or a copy-pasted variant) is called from **>1 call site** or in a loop | Reuse means the contract is now an API surface. Drift between copies is a guaranteed bug source |

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 f