/agentsop-module-shape-selection

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 o