factory-retro

Turn measured friction into harness changes.

Agents don't reliably remember what slowed them down, and asking them to write it up produces either nothing or noise. Three sources carry the evidence instead:

factory friction $ARGUMENTS
factory economics $ARGUMENTS
factory ci $ARGUMENTS

Friction is what wasted the agents' time inside a session; economics is what consumed context and the usage window (context burn, cache thrash, zero-result runs); CI is the clock agents wait on outside the session — workflow-scoped REST run watches in factory-merge/factory-ship sitting idle for however long GitHub Actions takes, per repo per workflow, with repeat-failure and slowdown-trend flags already computed. A repeat in any of the three is actionable — a tool that fails three runs running, a tool whose payloads dominate context burn, and an e2e job that's crept 40% slower over two weeks are all harness defects.

friction.mjs and economics.mjs need ~/.factory/logs/ transcripts, which only exist for runs the orchestrator itself dispatched. Invoked directly from the harness — you running /factory-retro in a repo without going through orchestrator dispatch — there may be no matching transcripts; friction.mjs exits with "no transcripts" in that case, which is expected, not a failure, so don't chase it as one. ci.mjs has no such dependency: it reads GitHub's own run history, so it carries the CI-reflection half of retro on its own even when the other two have nothing. Run all three regardless; treat an empty friction/economics result as "no session data this time," not as a broken retro.

Interactive sessions without transcripts file friction via /factory-friction at the end of /factory-work, /factory-merge, /factory-ticket, and /factory-ship (skipped when FACTORY_RUN_ID is set). Search Linear for FIP: issues and bodies containing ## Session friction — merge that evidence with the mechanical transcript analysis below before deciding what to fix.

Then read docs/friction-log.md for what is already known and what was already decided against — the point is a shrinking list, not an accumulating one.

What counts

Only two things are worth acting on:

Repeats across runs. A failure in one run is that ticket's problem. The same failure shape in three runs is the harness's problem, and fixing it pays every future run. The analyzer already groups by failure shape with paths and ids normalised, so the count is meaningful.

Time sinks that shouldn't be paid per ticket. A three-minute compile every ticket is nine minutes across three tickets; if one warm-up makes it seconds, that is the fix. Look for the same expensive command in every transcript.

Ignore one-offs, however annoying. A single flaky network call is not a harness defect, and chasing it adds a rule everyone must read forever.