| name | agent-friction-retro |
| description | Stop agent workflow spirals by inventorying blockers, fixing durable root causes, and documenting anti-friction improvements before moving on. |
Agent Friction Retro
Purpose: when a task takes too long for its scope, convert the wasted time into durable tooling, docs, tests, or workflow improvements instead of treating it as incidental pain.
When To Use
- The user says the agent struggled, spiraled, burned too much clock time, or should have moved faster.
- You hit the same failure class twice in one task.
- You rerun a broad suite because you cannot target the actual failing surface.
- CI fails for a local/CI environment mismatch that was predictable or automatable.
- Local verification leaves generated files, line-ending churn, dirty lockfiles, or other workspace noise.
- A command interface surprises you, drops quoted args, races with another check, or requires manual path guessing.
- You are tempted to say "flaky" without either proving it is external or removing the source of flakiness.
Hard Rule
Do not continue brute-forcing once a workflow defect is identified. Stop, name the defect, and patch the smallest durable fix that prevents the next agent from paying the same cost.
This is not optional cleanup. It is core engineering work because repeated agent friction silently taxes every future issue, PR, and review loop.
Anti-Spiral Protocol
- Freeze the loop.
- Write the blocker list before making more attempts.
- Classify each blocker as product bug, test bug, tooling gap, documentation gap, environment/config gap, reviewer/process gap, or agent mistake.
- For each blocker, ask whether a fresh agent would likely hit it again.
- Patch durable mechanics before retrying broad verification.
- Prefer narrow verification first, then restore the broader gate.
- Record the improvement in
docs/agentic/agentic-improvement-log.md or a more specific durable artifact.
- If the fix changes a repeatable workflow, update or create a skill and Codex wrapper.
Blocker Inventory Template
Use this structure in your scratch reasoning or PR notes:
| Blocker | Evidence | Class | Future risk | Durable fix | Verification |
| --- | --- | --- | --- | --- | --- |
| CI Linux snapshot missed | web-playwright visual failed on `*-chromium-linux.png` | tooling gap | high | add artifact adoption helper/docs | helper dry-run plus CI green |
Keep the inventory factual. Do not pad it with blame or vague "flakiness" labels.
Fix Selection
Prefer small durable fixes in this order:
- Deterministic script or command that removes manual guessing.
- Test harness stabilization that makes the intended narrow check runnable.
- Git attributes or ignore rules that eliminate generated status noise.
- Documentation update beside the command or runbook agents already read.
- Skill update when the lesson is a repeatable agent workflow.
- Follow-up issue only when the fix is too large for the current PR.
Avoid these anti-patterns:
- Re-running full suites repeatedly without narrowing the failure.
- Copying CI artifacts by hand when a script can map paths safely.
- Accepting generated dirty files as "normal."
- Encoding broad fuzzy behavior in product code just to satisfy one prompt.
- Opening a new docs-only issue when a tiny script or config patch would remove the friction immediately.
- Marking the PR done while the blocker remains likely to hit the next agent.
Verification Standard
For each durable fix, run the narrowest command that proves the fix and one representative broader gate when practical.
Examples:
npm --prefix apps/web run test:e2e:visual -- --grep legal.*privacy
npm --prefix apps/web run test:e2e:visual:adopt -- .github-run-artifacts/web-playwright-artifacts-visual --platform linux --filter privacy-full --dry-run
node scripts/ensure-workspace-install.mjs
If full verification is expensive or blocked, say exactly what was verified and what remains covered by CI.
Reporting Back
When the retro is done, include:
- The blocker list.
- The fixes made in this PR.
- Verification results.
- Any remaining risk or deferred follow-up.
Keep it direct. The goal is to show that the workflow tax was paid down, not just explained.
