---
name: agentsop-module-shape-selection
version: 0.1.0
description: >-
  ENHANCE overlay on [[dspy]] — the upfront rubric for choosing a reasoning SHAPE (Predict /
  ChainOfThought / ReAct / ProgramOfThought) BEFORE you write a prompt or pick an optimizer.
  The local `dspy` skill lists the modules but never surfaces the *selection criterion*:
  reasoning shape is chosen by task structure, not by reflexively defaulting to CoT.
  Activate every time a new LM-calling node/step is added to a pipeline. Do NOT activate for
  one-shot prompts, optimizer/teleprompter choice (that is the dspy SOP's job), or non-LM
  control flow. Search keywords: chain of thought vs ReAct, when to use CoT, reasoning type,
  ReAct vs CoT vs PoT, which dspy module, predict vs chain of thought.
---

# 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**:

| Trigger | Signal |
|---|---|
| New node | A LangGraph/CrewAI node body, or a `forward()` line, is about to call an LM |
| New `dspy.<Module>(Sig)` | You are typing `dspy.ChainOfThought(...)` on reflex — stop and run the rubric |
| Refactor | An existing `Predict` "feels weak" or a `ChainOfThought` "feels wasteful" |
| Pipeline growth | A multi-stage program adds a stage; each stage needs its own shape decision |
| Tool appears | A function/API/search/calculator is now available to the 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

| Task structure | Shape | DSPy module | Cost signature | Evidence |
|---|---|---|---|---|
| Lookup / classify / extract / format-convert (no reasoning needed) | **Predict** | `dspy.Predict(Sig)` | 1 call, no reasoning tokens — lowest overhead | [dspy.ai/learn/programming/modules/], lib `Predict` §2 |
| Analytic / judgement / multi-hop inference (reasoning helps, no tool) | **Chain of Thought** | `dspy.ChainOfThought(Sig)` | 1 call + `reasoning`/`rationale` field — **adds output tokens** | [dspy.ai/learn/programming/modules/], lib `ChainOfThought` §2 |
| Tool-use: search / API / DB / retrieval / calculator | **ReAct** | `dspy.ReAct(Sig, tools=[...])` | N calls — a think→act→observe loop | [dspy.ai/learn/programming/modules/], lib `ReAct` §2 |
| Math / counting / unit conversion / strict parsing | **Program of Thought** | `dspy.ProgramOfThought(Sig)` | 1 LM call → generated code → executed; answer grounded in execution | [dspy.ai/learn/programming/modules/], lib `ProgramOfThought` §2 |

### 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

| Situation | Action | Why |
|---|---|---|
| Math task but you trust the LM's mental arithmetic | Still prefer **PoT** | Code execution removes arithmetic hallucination [dspy.ai/learn/programming/modules/] |
| Reasoning helps AND a tool exists | **ReAct** (it does CoT *inside* the loop) | ReAct subsumes CoT when tools are present |
| Hard analytic case, single CoT is unstable | `dspy.MultiChainComparison` / `dspy.majority` over N CoT samples | Vote across samples — escalation, not a base shape [dspy-sop §4.2] |
| "Tool" is actually a pure Python function with no I/O | Inline the function; use **CoT or Predict**, not ReAct | A ReAct loop with a trivial deterministic helper is wasted calls (Case B) |

### 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.**

---

### Case B — "ReAct without tools is just CoT (with extra failure modes)"

**困境:** An engineer wants an "agentic" answer step and writes
`dspy.ReAct("question -> answer", tools=[])` — or with a single trivial helper that
does no real I/O. Is this actually agentic?

**约束:**
- ReAct's value is the **think → act → observe** loop over *real* tools (search, API,
  DB) [dspy.ai/learn/programming/modules/, lib `ReAct` §2].
- With no real tool, the loop has nothing to observe; it degenerates to reasoning —
  i.e. CoT — but pays for loop overhead and added parsing/failure surface.

**决策步骤:**
1. Classify (Step 1): Q2 "needs a real tool/action?" → **no** (empty or trivial tools).
   The card routes away from ReAct.
2. Recognize that **ReAct with no real tools is just CoT** — the reasoning happens, but
   the action/observation steps are dead weight that can hang or mis-parse.
3. If reasoning genuinely helps → use **`dspy.ChainOfThought`** directly. If it doesn't →
   **`dspy.Predict`**.
4. Add `dspy.ReAct(tools=[...])` back **only** when a real external capability appears
   (web search, retrieval, calculator API). Then ReAct subsumes CoT inside its loop.

**结果:** Replacing tool-less ReAct with CoT removes loop overhead and a class of
tool-parsing failures while preserving the reasoning. No capability is lost because none
existed.

**可提取的操作:** **ReAct earns its loop only when at least one real, I/O-bearing tool
exists. Tool-less ReAct → downgrade to CoT (or Predict).**

---

### Case C — "Math step: trust CoT's arithmetic or ground it with PoT?"

**困境:** A step computes "15% of 240, then subtract the 3-item average." The reflex is
`ChainOfThought` because it "shows the math." Is shown arithmetic *correct* arithmetic?

**约束:**
- LMs hallucinate arithmetic even when the reasoning prose looks right.
- `ProgramOfThought` generates and **executes** code, grounding the number in a real
  computation [dspy.ai/learn/programming/modules/, lib `ProgramOfThought` §2].

**决策步骤:**
1. Classify (Step 1): Q2 "needs deterministic computation?" → **yes (math)**. Card →
   **ProgramOfThought**, not CoT.
2. Use `dspy.ProgramOfThought("question -> answer")`; it emits `answer = 240*0.15 - ...`
   and runs it [lib `ProgramOfThought` §2].
3. Reserve CoT for the *framing* ("which numbers matter") only if that itself is
   ambiguous — then compose: CoT to extract operands → PoT to compute.

**结果:** PoT removes arithmetic hallucination at the cost of one code execution. CoT on
the same step ships numbers that *look* derived but may be wrong.

**可提取的操作:** **Any step whose answer is a computed number/count/parse defaults to
PoT. CoT's prose is not a substitute for executed code.**

---

## 6. 反模式与边界 (Anti-patterns & boundaries)

### Anti-patterns

1. **The CoT-everywhere reflex.** Reaching for `dspy.ChainOfThought` on every step
   "to be safe." Safe ≠ free; the reasoning field is a per-call token tax. CoT is the
   default *when unsure*, not the default *always* (Case A) [dspy.ai/learn/programming/modules/].
2. **ReAct with no real tools.** A `ReAct(tools=[])` or a ReAct over a trivial pure
   function is just CoT plus loop overhead and extra failure modes (Case B).
3. **CoT prose as a math guarantee.** Trusting a reasoning field's arithmetic instead of
   executing it. Use PoT for computed answers (Case C).
4. **Picking shape by feel after writing the prompt.** Shape is an *upfront* structural
   decision; choosing it post-hoc means the prompt was written against the wrong contract.
5. **Conflating shape with optimizer.** "MIPROv2 will fix it" — an optimizer cannot
   repair a wrong shape; it optimizes whatever shape you gave it [dspy.ai/learn/optimization/overview/].
6. **Predict on a genuinely analytic task.** Under-powering to save tokens when the task
   needs multi-hop reasoning — the mirror failure of the CoT reflex.
7. **One shape for the whole pipeline.** Each LM-calling step gets its own classify→pick;
   a retrieve→reason→format pipeline may be ReAct→CoT→Predict.

### Boundaries (where this overlay stops)

- **Optimizer / teleprompter choice** (BootstrapFewShot, MIPROv2, GEPA, finetune): not
  here — see [[agentsop-dspy]] §4. Shape first, optimizer second.
- **Signature design** (field names, types, `desc=`): the lib skill [[dspy]] Core
  Concepts §1. Shape assumes the signature exists.
- **Metric design and compile-cost guardrails:** [[agentsop-dspy]] §4.3–4.4.
- **One-shot / no-pipeline prompting:** out of scope; just call the LM.
- **Token-level output constraints** (force-valid-JSON): Outlines/Guidance, orthogonal
  to shape ([[agentsop-dspy]] §7).

---

## 7. 跨框架对照 (Cross-framework correspondence)

The shape decision is framework-independent; only the spelling changes.

| Reasoning shape | DSPy module | LangChain equivalent | Raw-prompting equivalent |
|---|---|---|---|
| **Predict** (lookup/classify, no reasoning) | `dspy.Predict(Sig)` | `LLMChain` / direct `model.invoke` with a plain template | Single prompt, "answer directly" — no scratchpad |
| **Chain of Thought** (analytic, no tool) | `dspy.ChainOfThought(Sig)` | `LLMChain` with a "think step by step" prompt; no agent | "Let's think step by step…" then answer |
| **ReAct** (tool-use loop) | `dspy.ReAct(Sig, tools=[...])` | `create_react_agent` / `AgentType.ZERO_SHOT_REACT_DESCRIPTION` + tools | Manual Thought/Action/Observation loop you parse yourself |
| **Program of Thought** (math/parse via code) | `dspy.ProgramOfThought(Sig)` | `PythonREPLTool` agent / `LLMMathChain` | "Write Python to compute the answer," then exec |

**Reading the table:** the *task-structure question* (reasoning? tool? compute?) is the
invariant. DSPy makes the choice a one-line module swap with a stable signature; LangChain
makes it an agent-type/chain choice; raw prompting makes it a scratchpad-format choice you
hand-maintain. The selection rubric in §3–§4 is the same in all three columns — only the
binding to code differs. This is why the overlay lives *above* [[dspy]]: the rubric
transfers even when you leave DSPy.

**Bridge to the rest of the stack:** once the shape is chosen here, hand off to
[[agentsop-dspy]] for metric + optimizer + compile, and to [[dspy]] for the module API,
signature syntax, and LM-provider wiring.

---

### Source map

- DSPy module semantics & "default to ChainOfThought" line: [dspy.ai/learn/programming/modules/]
- Local source `dspy-sop` SKILL.md §3 (Stage 1 module pick), §4.2 (module selection table)
- Local lib skill `~/.claude/skills/dspy/SKILL.md` §Core Concepts 2 (Predict/CoT/ReAct/PoT
  examples), Best Practices §1 ("start simple, iterate")
- Full evidence trace: `references/R1-source-evidence.md`
- Extracted operations: `intermediate/operation_candidates.json`