Prompt Chaining

Gated exit

Implement the Prompt Chaining pattern in this codebase, using the LLM client and language we already use.

## Goal

Turn a blog-post brief into a finished post through a fixed sequence of calls (outline, check, draft, polish), stopping early when the outline fails a code check.

## How it works

1. Define the chain in code as an ordered list of steps; each step names its prompt, its input and the one output it passes on. The model never picks the next step.
2. Call the model with the Step 1, outline prompt, filling in the brief and the audience, and parse the reply as JSON into a list of sections.
3. Run the gate in plain code: the JSON parses, it has between 4 and 6 sections, and every section has a non-empty heading and point.
4. If the gate fails, end the chain and return an error result holding the rejected outline and the name of the check that failed. Do not call the draft step.
5. If it passes, call the model with the Step 2, draft prompt, passing only the approved outline and the target word count.
6. Send the draft to a third call that polishes tone and clarity without changing the structure, and return its text as the post.

## Prompts

### Step 1, outline prompt

```markdown
You are planning a blog post for {{audience}}.

<brief>{{brief}}</brief>

Write an outline with 4 to 6 sections. Give each section a heading
and one sentence on what it must prove. Output JSON:
{"sections": [{"heading": "...", "point": "..."}]}
```

### Step 2, draft prompt

```markdown
Write the full post from this approved outline. Follow it exactly:
same sections, same order, no new sections.

<outline>{{outline}}</outline>

Keep to about {{word_count}} words and write in a plain, concrete voice.
```

## Stop rule

The chain ends after the polish step, or at the first failed gate. Nothing loops: each step runs once, so a run makes at most 3 model calls, plus one retry per failed call.

## Requirements

- Keep the section bounds (default 4 to 6) and the word count (default 800) as parameters, not literals inside a prompt.
- If a model call errors or times out, retry it once, then end the chain with an error that names the step.
- Pass each step only the fields it needs, as named values (outline, draft), never the whole conversation so far.
- Log every step's input, output, gate result and token count, so a bad post can be traced to the step that caused it.
- Add a test with a stub LLM whose outline has 2 sections; assert exactly one model call was made and the result is an error containing that outline.

Gate with retry

Implement the Prompt Chaining pattern (Gate with retry variant) in this codebase, using the LLM client and language we already use.

## Goal

Turn a brief into a finished post through fixed steps, where an outline that fails the code check is sent back with the error for a capped number of retries before the chain gives up.

## How it works

1. Define the chain in code as an ordered list of steps: outline, check, draft, polish. The model never picks the next step.
2. Call the model with the Step 1, outline prompt, filling in the brief and the audience, and parse the reply as JSON into a list of sections.
3. Run the gate in plain code: the JSON parses, it has between 4 and 6 sections, and every section has a non-empty heading and point. Collect every failed check as a short error message.
4. If the gate fails and attempts remain, call the outline step again with the same brief plus the error messages, and check the new outline.
5. If the gate passes, call the model with the Step 2, draft prompt, passing only the approved outline and the word count, then polish the draft in a third call and return it.

## Prompts

### Step 1, outline prompt

```markdown
You are planning a blog post for {{audience}}.

<brief>{{brief}}</brief>

{{#if errors}}
Your previous outline failed these checks. Fix every one:
<errors>{{errors}}</errors>
{{/if}}

Write an outline with 4 to 6 sections. Give each section a heading
and one sentence on what it must prove. Output JSON:
{"sections": [{"heading": "...", "point": "..."}]}
```

### Step 2, draft prompt

```markdown
Write the full post from this approved outline. Follow it exactly:
same sections, same order, no new sections.

<outline>{{outline}}</outline>

Keep to about {{word_count}} words and write in a plain, concrete voice.
```

## Stop rule

Stop after the polish step, or when the outline has failed the gate 3 times in total. In that case return an error result with the last outline and every error message, and do not draft.

## Requirements

- Make the attempt cap a parameter (default 3 attempts, so 2 retries); the retry loop must never run without one.
- Send the gate's error messages back verbatim and specifically ("3 sections, need 4 to 6"), never a bare "invalid".
- Treat a reply that is not valid JSON as a gate failure with the parse error as its message, so it uses the same retry path.
- Log each attempt's outline and errors, so a brief that keeps failing can be found and its prompt fixed.
- Add a test with a stub LLM whose first outline has 2 sections and whose second has 4; assert two outline calls, that the second prompt contains the error, and that a post is returned.

Incremental refine

Implement the Prompt Chaining pattern (Incremental refine variant) in this codebase, using the LLM client and language we already use.

## Goal

Summarize a document too long for one call by running a single refine step once per chunk, in order, carrying a running summary forward from chunk to chunk.

## How it works

1. Split the document in code into chunks that fit the context window with room to spare (default 2,000 tokens each), keeping their order and breaking at paragraph ends.
2. Start with an empty running summary.
3. For each chunk in order, call the model with the Refine prompt, passing the chunk, its position (3 of 40) and the running summary, and replace the summary with the reply.
4. If the new summary is longer than the length cap, call the model once with the Compress prompt, and keep the shorter of the two summaries.
5. After the last chunk, return the running summary.

## Prompts

### Refine prompt

```markdown
You are summarizing a long {{document_type}} one part at a time.

<summary_so_far>{{summary}}</summary_so_far>
<part number="{{index}}" of="{{total}}">{{chunk}}</part>

Update the summary so it also covers this part. Keep earlier
points unless this part contradicts them, keep events in order,
and stay under {{max_words}} words. Return only the summary.
```

### Compress prompt

```markdown
Shorten this summary to under {{max_words}} words. Keep events
in order, keep every name the later parts may need, and drop
detail before dropping events. Return only the summary.

<summary>{{summary}}</summary>
```

## Stop rule

Stop after the last chunk has been folded in. The loop runs exactly once per chunk, so the number of calls is fixed by the input's length, plus at most one compression call per chunk.

## Requirements

- Make the chunk size (default 2,000 tokens) and the summary length cap (default 500 words) parameters.
- Process chunks strictly in order; the summary after chunk i must be the only memory passed to chunk i + 1.
- If a refine call errors, retry it once; if it fails again, stop and return the summary so far with the index of the chunk that failed.
- Save the summary after every chunk, so a long run can resume from the last good chunk.
- Add a test with a stub LLM that replies "S" plus the chunk number; feed 3 chunks and assert 3 calls, that call 3 received "S2" as the summary, and that "S3" is returned.