Agentsop Module Shape Selection

M2 — Module-Shape Selection (CoT / ReAct / PoT / Predict)

"Pick the lowest-power Module that works. Default to ChainOfThought." — DSPy docs [dspy.ai/learn/programming/modules/]

This overlay sharpens that line into a rubric: the default is not a law. The shape is a function of the task structure, and CoT is only one of four answers.

This is an enhancement overlay. It assumes the [[dspy]] library skill is loaded (it provides dspy.Predict, dspy.ChainOfThought, dspy.ReAct, dspy.ProgramOfThought APIs and install). This file adds only the decision the lib skill leaves implicit. Cross-link: [[dspy]], and the optimizer SOP [[agentsop-dspy]].

1. 何时激活 (When to activate)

Activate the instant you are about to add or wrap an LM-calling step:

Do NOT activate when:

• The work is a one-shot prompt — just call the LM; shape ceremony has no payoff.
• You are choosing the optimizer / teleprompter (MIPROv2, GEPA, BootstrapFewShot) — that is the [[agentsop-dspy]] workflow, a later stage. Shape comes first, optimizer second.
• The step is non-LM control flow (a if, a DB read, a deterministic transform).

Shape selection is upstream of optimization. You pick the shape in Stage 1 (Programming) of the dspy SOP, before any metric or compile [dspy.ai/learn/].

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

Reasoning shape is chosen by task structure, not by defaulting to CoT.

The lib skill shows four modules side by side and a "Best Practices" note that says "Start with Predict, add ChainOfThought if needed" [~/.claude/skills/dspy Best Practices §1]. In practice that collapses into a CoT-everywhere reflex, because "if needed" is never operationalized. This overlay operationalizes it.

A module's shape is the control-flow contract between the LM and your code:

                 does the answer need        is there a real
                 intermediate reasoning?      tool to call?
                         │                          │
   simple lookup ── no ──┤                          │
   /classify   ─────────►│ Predict                  │
                         │                          │
   analytic /   ── yes ──┤── no tool ──────────────►│ ChainOfThought
   judgement            │                          │
                         │                          │
   needs to act ─────────┼── yes, real tool ───────►│ ReAct(tools=[...])
   /look things up      │                          │
                         │                          │
   math / counting ──────┴── deterministic compute ►  ProgramOfThought
   / strict parsing                                   (code grounds answer)

Three shifts the agent must internalize:

1. The default is a probe, not a destination. "Default to CoT" means "when unsure, CoT is the safe baseline" — not "always ship CoT." Every CoT you ship that a Predict would have matched is pure token tax [dspy.ai/learn/programming/modules/].

2. Shape is structural, optimizer is statistical. Shape = which control flow (this overlay). Optimizer = which demos/instructions get baked in ([[agentsop-dspy]] §4). A wrong shape cannot be fixed by a better optimizer — MIPROv2 on the wrong shape just optimizes the wrong thing [dspy.ai/learn/optimization/overview/].

3. Each shape has a cost signature. Predict ≈ 1 call, no reasoning tokens. CoT ≈ 1 call + a reasoning/rationale field (more output tokens). ReAct ≈ N calls (a tool loop). PoT ≈ 1 LM call + code execution. Shape choice is a cost choice.

3. SOP (Classify → Pick → Measure)

A three-step gate, run per LM-calling step (not per pipeline):

Step 1 — Classify the task structure

Answer two yes/no questions about the step's output:

• Q1: Does a correct answer require visible intermediate reasoning? (Multi-hop inference, judgement, "why", trade-off weighing → yes. Lookup, label, format-conversion → no.)
• Q2: Does producing the answer require acting — calling a tool, fetching data, or running deterministic computation? (Search/API/DB → tool. Arithmetic/counting/strict-parse → computation. Neither → no.)

Step 2 — Pick the shape from the selection card (§4)

Map the (Q1, Q2) answers straight onto the card. Do not negotiate with the reflex.

Step 3 — Measure whether the shape earns its cost

A shape is only justified if it beats the cheaper shape below it. Before shipping anything heavier than Predict:

1. Run the candidate shape and the next-cheaper shape on 5–10 hand-picked examples.
2. Diff outputs with dspy.inspect_history(n=3) [dspy.ai/learn/programming/modules/].
3. Keep the heavier shape only if it changes answers for the better. If CoT and Predict produce the same labels on a classify task, ship Predict.
4. Record the call in intermediate/operation_candidates.json so the next node reuses the reasoning instead of re-deriving it.

Exit criterion: the chosen shape produces plausible outputs on 5+ examples AND no cheaper shape matches it. Then — and only then — proceed to metric + optimizer ([[agentsop-dspy]]).

4. 操作模型 (Selection card)

4.1 The four shapes

4.2 Cost note — CoT is not free

ChainOfThought adds a generated reasoning field to every call. On a high-volume classify step (e.g. routing 100k tickets/day), that reasoning field is pure cost with zero accuracy gain if the labels don't change. The lib skill's "add CoT if needed" [lib Best Practices §1] is correct but under-specified: needed means "Step 3 measured a lift." Default to CoT when unsure; ship Predict when measured equal.

4.3 Tie-breakers and escalation

4.4 Selection card as a one-liner

no reasoning, no tool        → Predict
reasoning, no tool           → ChainOfThought
any real tool / action       → ReAct(tools=[...])
math / count / strict parse  → ProgramOfThought

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

Case A — "CoT on a simple classify wastes tokens"

困境: A pipeline routes incoming support tickets into 6 categories. The engineer's reflex was dspy.ChainOfThought("ticket -> category") because "reasoning is always safer." Volume is 100k tickets/day. Is the reasoning field earning its cost?

约束:

• The output is one of 6 fixed labels — a closed-set classification.
• Every CoT call emits a reasoning field (extra output tokens) × 100k/day.
• Accuracy target already met by a simpler shape in spot-checks (unverified).

决策步骤 (Step 3 of the SOP, made concrete):

1. Classify (Step 1): Q1 "needs visible reasoning?" → no (closed-set label). Q2 "needs a tool/compute?" → no. The card says Predict.
2. The reflex said CoT. Run both on 10 hand-picked tickets, diff with dspy.inspect_history(n=3) [dspy.ai/learn/programming/modules/].
3. If the 6 labels come out identical, the reasoning field changed nothing — it is pure token tax at 100k/day. Ship Predict.
4. If CoT flips 1–2 ambiguous edge cases correctly, keep CoT only for those — or move ambiguity handling to a second, cheap Predict triage stage.

结果: On closed-set classification, Predict typically matches CoT. The CoT-everywhere reflex would have shipped a per-call reasoning surcharge for no accuracy.

可提取的操作: A closed-set classify/lookup step defaults to Predict. Promote to CoT only after Step 3 measures a label change — never on reflex.