file-friction

Files the friction worked around during a task as deduplicated GitHub issues so a later agent fixes the cause. Use when finishing /commit, before ending any task that hit a flaky or slow gate, a confu

SKILL.md

GitHub

File Friction

Agents work around friction instead of fixing it, and the workarounds compound across every Claude Code and Codex session. This skill turns each workaround into an issue that /triage can promote to ready-for-agent. It files issues only — never fix the friction inside the current task unless it is in scope.

1. List candidates

Review this task's transcript, commands and SESSION_LOG.md entry. A candidate is something you worked around, not something you fixed:

  • A gate that failed for reasons unrelated to the change (flaky test, timeout, runner disk, drift).
  • A step that was slow enough to change how you worked.
  • A doc, AGENTS.md rule or skill that was wrong, stale, ambiguous or missing.
  • A tool, hook or script that failed or needed a retry, restart or manual step.
  • A helper you rewrote because you could not find the shared one (see docs/agents/primitives.md).

Drop anything already fixed in this task, caused by your own mistake, or purely environmental to one machine with no repo-side fix. If nothing qualifies, say "No friction filed" and stop.

2. Deduplicate

For each candidate, search open friction issues with two or three key terms:

gh issue list --label friction --state open --search "<terms>" --json number,title,url

If one matches, add a comment with the new evidence and the date instead of filing a duplicate. Start comments with the disclaimer below.

3. File

File at most 3 new issues per task; keep the most costly. Use this body:

gh issue create --label friction --label needs-triage --title "friction: <symptom in under 60 chars>" --body "$(cat <<'EOF'
> *This was generated by AI during friction capture.*

**Filed by:** <Claude Code | Codex> · <branch> · <YYYY-MM-DD>

**What happened**
<one or two sentences>

**Workaround used**
<what the agent did instead>

**Suggested fix**
<smallest change that removes the friction, with file paths>

**Evidence**
<exact command and trimmed output>
EOF
)"

The repository is public. Never include secrets, tokens, .env values, client data, personal data, Sentry event payloads or anything from /private/. Paths, commands and redacted error text are fine.

4. Record

Add friction: #<n>, #<m> (or friction: none) to this task's SESSION_LOG.md entry and to the final summary for the user.