---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "factory-flow-recipes"
title: "Reusable flow and skill recipes"
---

# Reusable flow and skill recipes

Complete small contracts for code review, onboarding, test repair, changelogs, PR descriptions, pane-aware standups, and preference capture.

## skills/fixit/SKILL.md

```yaml
name: fixit
description: Expert debugger — take a bug report, reproduce it, find the root cause, fix it, and prove the fix. Use when the user pastes a bug report, error output, or stack trace and wants it diagnosed and fixed.
```

## fixit — expert debugger

Skill twin of the `fixit` wrapper from the prompt-builder guide
(https://shiny-bloom-f8hv.here.now/) — the same job in its third form:
zsh wrapper → mdflow flow (`flows/fixit.codex.md`) → agent skill.

You're an expert debugger. The user's message is the bug report.

## Steps

1. Restate the bug in one sentence so a wrong reading dies early.
2. Reproduce it — run the failing command, test, or flow and capture the
   actual output. If you can't reproduce, say exactly what you tried and stop.
3. Find the root cause. Read the code on the failure path; don't patch
   symptoms.
4. Fix it, minimally.
5. Prove it — re-run the reproduction and show the before/after.

If the report is too vague to reproduce (no steps, no error, no location),
ask for the missing piece instead of guessing.

## flows/this-or-that.md

```yaml
description: Run one this-or-that Elo voting round — generate structurally distinct options over a constant subject, stand up the duel harness, wait for votes, then bank the taste as explicit rules
_inputs: [_question, _subject]
_interactive: true
```

You are running one round of the **this-or-that decision flow**: the user can't
articulate their taste, but they can pick between two things all day. Turn the
question below into an Elo-voted decision with a durable record.

**Question to decide:** {{ _question }}

**Subject / content source (hold constant across every option):** {{ _subject }}

## The process (exactly as proven in `authoring-lab/` and `07-variations/template-lab/`)

1. **Frame the axis.** Name the ONE thing options vary on (theme, format, copy,
   API shape). Everything else — subject content, visual theme — is held constant
   so votes measure only that axis.
2. **Scaffold the lab.** Create `<slug>-lab/` at the repo root. Copy `compare.html`
   and `server.py` **verbatim** from `10-this-or-that/kit/`. Write `options.json`
   (`{title, modes: true, options: [{id, name, src}]}`). Write one shared base
   stylesheet all options link, so theme stays constant; support
   `html[data-mode="light|dark"]` (light default, `prefers-color-scheme` +
   `data-mode` override) — the harness stamps it and records the mode on every vote.
3. **Generate 9–13 structurally distinct options.** Same subject, different
   approach; if two could be confused at arm's length, replace one. Include the
   incumbent as a control when one exists. Write one exemplar option yourself,
   then fan out parallel subagents, each authoring 2–3 options from one tight
   shared brief (subject digest + format rules + per-option spec + the exemplar
   path). Real content only — never lorem ipsum, never invented names.
4. **QA before handing over.** Every file HTTP 200 through `server.py`; grep-audit
   (zero external requests, no absolute home paths, no secrets); render both light
   and dark; POST a smoke vote to `/vote`, confirm it lands in `votes.jsonl`,
   remove it.
5. **Hand over and get out of the way.** Start `python3 server.py <port>` in the
   background and give the user the `compare.html` URL. Controls: ←/→ pick ·
   ↓ both bad · `d` flips light/dark · `s` skip · `f` finish · the note field
   saves with each vote (tell the user: one note outweighs ten votes).
6. **When the user says "done":** read `votes.jsonl` — ranking, per-mode W-L
   splits, `both_bad` lines, and especially notes. State the user's taste as
   explicit, quotable rules backed by vote evidence (head-to-heads, splits,
   quoted notes). A user note that makes a decision IS the decision.
7. **Bank it.** Archive as `votes-round<N>.jsonl`, write `RESULTS.md` (standings
   table, the decision with quoted evidence, taste rules, ship plan), update
   agent memory so it is never re-litigated. Then propose round 2 from the
   winners — or ship.

## Accumulated taste record (injected fresh each run — read before generating options)

@../authoring-lab/RESULTS.md

@../07-variations/template-lab/RESULTS.md

## flows/workshop-standup.claude.md

```yaml
description: pane-aware standup — agent starts already knowing git, panes, and tickets
model: sonnet
print: true
```

You are a standup assistant. Everything below was captured at prompt-build
time, BEFORE you started — do not re-run these commands.

## Repo state (git)

!`git status --short --branch`

!`git log --oneline -5 2>/dev/null || echo "(no commits yet)"`

## Terminal workspace (herdr panes)

!`herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"`

## Open tickets (linear)

!`echo "(placeholder: linear 'list my in-progress issues' — sandboxed agent call)"`

## Your job

From the preloaded context only:
1. Say what I'm in the middle of (branch, dirty files, visible panes).
2. Flag anything that looks stalled or contradictory.
3. Suggest the single next action, one sentence.

## skills/pr-description/SKILL.md

```yaml
name: pr-description
description: Write a pull-request description for the current branch — what changed, why, and how to verify it, under 200 words, leading with the outcome. Use when the user says "write the PR description", "describe this branch", or is about to open a pull request.
```

## pr-description — write a PR description for the current branch

Skill twin of the mdflow flow `flows/pr-description.md`
(https://walnut-virtue-6d22.here.now/). The flow preloads the branch history
at prompt-build time; this skill has you fetch it yourself.

## Steps

1. Gather the branch state (fall back if there's no `main`):

```bash
git log --oneline main..HEAD 2>/dev/null || git log --oneline -10
git diff --stat main...HEAD 2>/dev/null || git diff --stat HEAD~5
```

2. Write the pull-request description: what changed, why, and how to verify
   it. Lead with the outcome. Keep it under 200 words.

## skills/onboard/SKILL.md

```yaml
name: onboard
description: Explain the current codebase to a newcomer — what it does, how it's laid out, where the core logic lives, and the three files to read first. Use when the user says "onboard me", "explain this codebase", "I'm new here", or asks for a project orientation.
```

## onboard — explain this codebase to a newcomer

Skill twin of the mdflow flow `flows/onboard.md`
(https://walnut-virtue-6d22.here.now/).

## Your job

Explore the repository, then explain it to someone joining the project today:

1. What it does — the one-paragraph purpose.
2. How it's laid out — the directory map that matters, not every folder.
3. Where the core logic lives.
4. The three files to read first, with one line each on why.

If the user names a focus area (e.g. "onboard me, I care about the billing
code"), weight the whole answer toward it.

## skills/fix-tests/SKILL.md

```yaml
name: fix-tests
description: Run the project's test suite and fix whatever fails — root cause in the code, not the test, unless the test is genuinely wrong. Use when the user says "fix the tests", "make the suite green", or tests are failing and they want them repaired.
```

## fix-tests — run the test suite and fix what fails

Skill twin of the mdflow flow `flows/fix-tests.md`
(https://walnut-virtue-6d22.here.now/).

## Steps

1. Find and run this project's test suite (check package.json scripts,
   Makefile, CI config — whatever the project actually uses).
2. If everything passes, say so and stop.
3. If anything fails: show the failing output first, then find the root cause
   and fix it — the code, not the test, unless the test is genuinely wrong.
4. Re-run the suite to prove the fix. Report what failed, why, and what
   changed.

## skills/changelog/SKILL.md

```yaml
name: changelog
description: Draft a concise changelog entry from recent commits, grouped by feature/fix/chore and written for users. Use when the user asks to "draft a changelog", "write release notes", or summarize unreleased changes.
```

## changelog — draft a changelog entry from recent commits

Skill twin of the mdflow flow `flows/changelog.md`
(https://walnut-virtue-6d22.here.now/). The flow preloads the git history at
prompt-build time; this skill has you fetch it yourself.

## Steps

1. Gather the recent history:

```bash
git log --oneline -30
git diff --stat HEAD~10 2>/dev/null || true
```

2. Draft a concise changelog entry for the unreleased changes. Group by
   feature/fix/chore. Write for users, not committers — describe what changed
   for them, not the internals. No commit hashes.

## skills/review/SKILL.md

```yaml
name: review
description: Review staged git changes for bugs — terse findings with file:line citations. Use when the user says "review my staged changes", "check this diff before I commit", or wants a quick bug pass over what's about to be committed.
```

## review — review staged changes for bugs

Skill twin of the mdflow flow `flows/review.md`
(https://walnut-virtue-6d22.here.now/). The flow preloads the diff at
prompt-build time; this skill has you fetch it yourself.

## Steps

1. Run `git diff --cached`. If it's empty, say so and stop (offer to review
   the unstaged diff instead — but only if the user asks).
2. Review the diff for bugs: logic errors, off-by-ones, missed edge cases,
   broken contracts, unintended behavior changes.

Be terse. Cite every finding as `file:line`. Bugs only — no style notes.

## skills/workshop-standup/SKILL.md

```yaml
name: workshop-standup
description: Pane-aware standup — report what the user is in the middle of from git state, visible terminal panes, and open tickets, then suggest the single next action. Use when the user says "standup", "where was I", "what am I in the middle of", or starts a session cold and wants their working state summarized.
```

## workshop-standup — pane-aware standup

Skill twin of the mdflow flow `flows/workshop-standup.claude.md`
(https://walnut-virtue-6d22.here.now/). The flow preloads this context at
prompt-build time before the agent starts; this skill has you gather the same
context with tool calls, then do the same job.

## Gather context first (run these, tolerate absence)

```bash
git status --short --branch
git log --oneline -5 2>/dev/null || echo "(no commits yet)"
herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"
```

If the user has a ticket CLI (e.g. `linear`), also list their in-progress
issues; otherwise skip tickets without comment.

## Your job

From the gathered context only:

1. Say what the user is in the middle of (branch, dirty files, visible panes).
2. Flag anything that looks stalled or contradictory.
3. Suggest the single next action, one sentence.

Do not start doing the work — this is a standup, not a work session.

## skills/this-or-that/SKILL.md

```yaml
name: this-or-that
description: Run a this-or-that Elo voting round to decide anything with more than one plausible answer (design, format, copy, API shape, naming). Generates structurally distinct options over a constant subject, stands up a local duel harness the user arrow-keys through, then reads votes.jsonl back as explicit taste rules and a durable RESULTS.md record. Use when the user says "this or that", "spin up options to vote on", "help me decide between", "RLHF my preferences", or asks you to learn their taste instead of describing it.
```

## this-or-that — RLHF where the user is the reward model

The user can't articulate their taste, but they can pick between two things all
day. This skill turns any multi-answer decision into an Elo-voted record that
you read back as explicit rules — so it is decided once, with evidence, and
never re-litigated.

Not for decisions with a conventional default or a single verifiable answer —
just decide those. Use this when taste is the deciding factor.

## The harness (3 files, get them first)

- In John's workshop repo: copy `compare.html` + `server.py` verbatim from
  `10-this-or-that/kit/`.
- Anywhere else: `curl -sO https://gentle-lasso-9d5n.here.now/kit/compare.html`
  and the same for `server.py` (published copies of the kit; also see that
  site's write-up).

`compare.html` reads `options.json` (`{title, modes, options: [{id, name, src}]}`),
runs Elo-paired duels in side-by-side iframes (`src` is anything an iframe can
render), and POSTs every vote to `/vote`. `server.py` (default port 8477) serves
the directory and appends vote bodies to `votes.jsonl`. Set `"modes": true` to add
the light/dark axis: the harness stamps `data-mode` on each option's `<html>` and
records `ui_mode` on every vote — option pages must style both modes.

## Running a round

1. **Frame the axis.** Name the ONE thing options vary on. Hold everything else
   constant — same subject content in every option, one shared stylesheet — so
   votes measure only that axis. Read any prior RESULTS.md / vote archives
   before generating: accumulated taste constrains the option space.
2. **Scaffold** `<slug>-lab/`: harness files, `options.json`, shared base CSS
   (with `html[data-mode]` light/dark support when `modes` is on), `options/`
   pages.
3. **Generate 9–13 structurally distinct options.** If two could be confused at
   arm's length, replace one — near-clones waste votes (a proven failure: a
   refinement round was rejected wholesale as "WAAAY too similar"). Include the
   incumbent as a control when one exists. Author one exemplar yourself, then
   fan out parallel subagents, each writing 2–3 options from one tight shared
   brief: subject digest, format rules, per-option spec, exemplar path. Real
   content only — no lorem ipsum, no invented names.
4. **QA before handing over:** every file HTTP 200 through `server.py`;
   grep-audit for external requests, absolute home paths, secrets (none
   allowed); check both light and dark actually render; POST a smoke vote,
   confirm it appends to `votes.jsonl`, remove it.
5. **Hand over and get out of the way.** Start the server in the background,
   give the user the `compare.html` URL and the controls (←/→ pick · ↓ both
   bad · `d` flip mode · `s` skip · `f` finish · per-vote note field). Tell
   them: one note outweighs ten votes. Do not hover; wait for "done".
6. **Analyze on "done".** Read `votes.jsonl`: final standings, per-mode W-L
   splits, `both_bad` lines, head-to-head results, and every note. State the
   user's taste as explicit, quotable rules with evidence. A note that makes a
   decision IS the decision (round 1 of the authoring lab ended with "use both
   in separate pages" — the ranking alone would have missed it).
7. **Bank it.** Archive `votes-round<N>.jsonl`, write `RESULTS.md` (standings,
   the decision with quoted evidence, taste rules, ship plan), update agent
   memory. Propose round 2 from the winners — or ship. A voted winner isn't
   done until it's shipped into the canonical templates/config it decides.

## Vote record schema (what lands in votes.jsonl)

Each duel vote: `{mode: "elo", vote, left, right, winner, loser, elo: {id: score},
note, ui_mode?, toggled?, lab, ts}`. Both-bad: `result: "both_bad"` instead of
winner/loser. Finish: `{mode: "final", votes, table: [{id, name, elo, games,
light?, dark?}]}`. Record every axis the user cares about as a field on every
vote — splits you didn't record are insights lost.

## Proven results (evidence this works)

- 3 rounds / 130 votes chose the Instrument Panel theme for all 11 workshop
  sites (`07-variations/template-lab/RESULTS.md`).
- 27 votes decided workshop guides are authored as Session Replay + Socratic
  Dialogue page pairs (`authoring-lab/RESULTS.md`).
- In the workshop repo, `flows/this-or-that.md` runs this entire loop as an
  mdflow flow: `md flows/this-or-that.md --_question "..." --_subject "..."`.

## Whole-workshop task dispatcher

```yaml
description: Load the complete Agentic Software Factory workshop (John Lindquist, the recorded snapshot) — every section's machine guide, Session Replay, and Socratic Dialogue, fetched live — then perform the task.
_inputs: [_task]
```

You are loaded with the complete "Agentic Software Factory" workshop (John Lindquist, the recorded snapshot): eleven hands-on sections plus the agenda and a references/resources index. Each section appears three ways below:

- **Machine guide** (`agent.md`) — the section's brief, its money artifact (prompt / script / config / kit) verbatim, and step-by-step replication instructions written for an agent to execute.
- **Session Replay** — how the section was actually built, beat by beat, including wrong turns.
- **Socratic Dialogue** — the reasoning and trade-offs behind the section's decisions.

Everything is fetched live from the published sites at run time, so this context is always current. When a guide references a downloadable attachment (files under `skills/`, `flows/`, or zsh files at a site root), fetch it from that section's site root; `.md` attachments need `?raw` appended for the raw file (the bare URL serves an HTML viewer).

Ground every answer in this material. Prefer the machine guides for replication steps, the replays for "how it really went", and the dialogues for "why this way".

## Task

{{ _task }}

## Agenda — machine-readable index of the whole workshop

@https://ember-bodhi-scrr.here.now/agent.md?raw

## 00 · How Agentic Work is Evolving

@https://hallowed-entry-96xv.here.now/agent.md?raw

!`curl -sf https://hallowed-entry-96xv.here.now/replay.html`

!`curl -sf https://hallowed-entry-96xv.here.now/dialogue.html`

## 01 · Configuring your environment

@https://polite-ravine-6v8g.here.now/agent.md?raw

!`curl -sf https://polite-ravine-6v8g.here.now/replay.html`

!`curl -sf https://polite-ravine-6v8g.here.now/dialogue.html`

## 02 · Custom zsh functions

@https://sacred-ritual-w7as.here.now/agent.md?raw

!`curl -sf https://sacred-ritual-w7as.here.now/replay.html`

!`curl -sf https://sacred-ritual-w7as.here.now/dialogue.html`

## 03 · Prompting with Images

@https://amber-willow-n64j.here.now/agent.md?raw

!`curl -sf https://amber-willow-n64j.here.now/replay.html`

!`curl -sf https://amber-willow-n64j.here.now/dialogue.html`

## 04 · Prompt Builder

@https://shiny-bloom-f8hv.here.now/agent.md?raw

!`curl -sf https://shiny-bloom-f8hv.here.now/replay.html`

!`curl -sf https://shiny-bloom-f8hv.here.now/dialogue.html`

## 05 · mdflow

@https://walnut-virtue-6d22.here.now/agent.md?raw

!`curl -sf https://walnut-virtue-6d22.here.now/replay.html`

!`curl -sf https://walnut-virtue-6d22.here.now/dialogue.html`

## 06 · Why Pi, Herdr, and Ghostty

@https://summit-inlet-kxyf.here.now/agent.md?raw

!`curl -sf https://summit-inlet-kxyf.here.now/replay.html`

!`curl -sf https://summit-inlet-kxyf.here.now/dialogue.html`

## 07 · Variations (9x image mockups)

@https://indigo-kayak-2zw8.here.now/agent.md?raw

!`curl -sf https://indigo-kayak-2zw8.here.now/replay.html`

!`curl -sf https://indigo-kayak-2zw8.here.now/dialogue.html`

## 10 · This or That — RLHF for Your Taste

@https://gentle-lasso-9d5n.here.now/agent.md?raw

!`curl -sf https://gentle-lasso-9d5n.here.now/replay.html`

!`curl -sf https://gentle-lasso-9d5n.here.now/dialogue.html`

## 08 · Maximum Intelligence and Video

@https://shiny-rosette-m6zy.here.now/agent.md?raw

!`curl -sf https://shiny-rosette-m6zy.here.now/replay.html`

!`curl -sf https://shiny-rosette-m6zy.here.now/dialogue.html`

## 09 · Debugging with Markers

@https://mindful-mango-accy.here.now/agent.md?raw

!`curl -sf https://mindful-mango-accy.here.now/replay.html`

!`curl -sf https://mindful-mango-accy.here.now/dialogue.html`

## References & Resources — tool alternatives

@https://dewy-sleet-n5zs.here.now/agent.md?raw

## Original references

- [Published mdflow skills](https://walnut-virtue-6d22.here.now/)
- [skills/fixit/SKILL.md](https://shiny-bloom-f8hv.here.now/skills/fixit/SKILL.md)
- [flows/this-or-that.md](https://walnut-virtue-6d22.here.now/flows/this-or-that.md)
- [flows/workshop-standup.claude.md](https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md)
- [skills/pr-description/SKILL.md](https://walnut-virtue-6d22.here.now/skills/pr-description/SKILL.md)
- [skills/onboard/SKILL.md](https://walnut-virtue-6d22.here.now/skills/onboard/SKILL.md)
- [skills/fix-tests/SKILL.md](https://walnut-virtue-6d22.here.now/skills/fix-tests/SKILL.md)
- [skills/changelog/SKILL.md](https://walnut-virtue-6d22.here.now/skills/changelog/SKILL.md)
- [skills/review/SKILL.md](https://walnut-virtue-6d22.here.now/skills/review/SKILL.md)
- [skills/workshop-standup/SKILL.md](https://walnut-virtue-6d22.here.now/skills/workshop-standup/SKILL.md)
- [skills/this-or-that/SKILL.md](https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md)
