agent-friction-ledger

Agent Friction Ledger

Turn repeatable agent friction into a small, actionable local artifact. This skill is opt-in and never sends session data outside the workspace.

Trigger

Use only when:

• the user explicitly asks for a friction report or review.

Do not run merely because a task had normal shell output, a single failed command, or a clean completion.

Capture Rules

Record only friction that is actionable and evidenced by the current task:

• repeated blocker or retry loop;
• misleading, incomplete, or contradictory error;
• missing, stale, or hard-to-find documentation;
• tool, provider, environment, or version incompatibility;
• manual workaround that should become a durable improvement.

Do not record every tool call, full conversation, raw logs, private URLs, credentials, personal data, client data, or unrelated working-tree changes.

Workflow

1. Name the task boundary and identify only the material friction events.
2. For each event, record: symptom -> attempted -> root cause -> resolution -> durable fix.
3. Mark confidence: confirmed, likely, or unresolved. Do not turn a guess into a root cause.
4. Redact or omit sensitive content before writing.
5. Write a local report to an ignored or private location only. Default to .git/agent-friction/YYYY-MM-DD-<task>.md unless the repo defines another approved ignored path.
6. Group action items under docs, tooling, skill/process, and research.
7. Propose the smallest durable change, but do not apply it without normal task authorization.

Report Shape

# Agent Friction Report: <task>

## Scope
## Material Friction
### <short label>
- Symptom:
- Attempted:
- Root cause: <confirmed|likely|unresolved>
- Resolution:
- Durable fix:

## Action Items
### Docs
### Tooling
### Skill / Process
### Research

## Decision
- Keep local / propose follow-up / no durable change

Guardrails

• Local Markdown only. Never POST to a viewer, telemetry endpoint, or external API.
• Never write to a tracked repo path by default. If no ignored/private location exists, stop and ask before writing.
• A friction report is not permission to create a ticket, alter a skill, edit docs, or change a process.
• Prefer one concise report over a growing per-turn buffer.
• If the task contains regulated, personal, client, deal, financial, or credential data, record the abstract failure mode only.