record-usage-issues

name

record-usage-issues

description

Record friction and bugs encountered while using or operating any project, into an append-only Markdown log (AGENT_ISSUES.md) that the user can later send back to the project's author for fixes. Trigger ONLY when the user explicitly asks for it — either by invoking this skill by name, or by clearly telling you to record/collect usage problems, e.g. "记录这个问题", "记一下这个 bug", "把踩的坑记下来", "接下来把用这个项目遇到的问题都记录下来", "log that bug", "note this for the author", "write down what went wrong", "from now on log any issues you hit while using this repo", or "collect the issues you ran into testing this tool". Do NOT trigger on your own: if the user has not asked you to record issues, do not start a log just because you happened to hit a bug — handle the problem as part of the normal task instead. Once the user has explicitly turned issue-recording on, keep logging qualifying problems you encounter for the rest of that session. This skill is project-agnostic — it works for any codebase, CLI, or tool you're operating.

Record Usage Issues

What this is for

You are operating inside a project that someone else built and handed off. While you carry out the user's actual tasks, you will sometimes hit friction: a command in the README doesn't work, a script crashes, the docs describe behavior that doesn't match reality, a dependency is missing, a default is wrong, or you find a genuine bug.

The author can't see any of this. The purpose of this skill is to leave a paper trail: a single append-only Markdown file that the user can mail back so the author can fix and improve the project. Think of yourself as a field tester filling out a defect log while you work — not stopping the job, just noting what tripped you up and how you got around it.

This skill is opt-in. Only record issues when the user has explicitly asked you to — by invoking the skill, or by telling you to log/collect the problems you run into with the project. Do not start a log on your own initiative just because you hit a bug; if the user never asked, simply deal with the problem as part of the task. Once the user has turned recording on, treat it as standing for the rest of the session: keep logging the qualifying problems you encounter without asking again each time.

The value of the log is signal density. A focused list of real, reproducible problems is worth far more to the author than a noisy diary of every minor thing. Optimize for "would the author want to fix this?"

When to log (and when not to)

Log it when the problem is the project's fault and the author would plausibly want to fix it:

• A documented command, flag, or example fails or does something different than documented.
• A script/tool throws an error, crashes, hangs, or returns a wrong result.
• Setup/install steps are missing, out of order, or don't work as written.
• Behavior contradicts the README, comments, schema, or other docs.
• A confusing API, unclear error message, missing file, or wrong default that cost you time.
• Any outright bug, even one you found a workaround for.

Don't log noise that isn't actionable for the author:

• Your own slips that you immediately corrected (a typo in a path, forgetting to cd).
• Pure environment issues unrelated to the project (your network was down) — unless the project should have handled it more gracefully, in which case log that angle.
• The same issue twice — if you already logged it this session, don't duplicate it. If it recurred in a meaningfully different place, add a short note to the existing entry instead.

When unsure, lean toward logging but keep it short. A borderline entry the author skims past is cheap; a real bug that went unrecorded is expensive.

Where to write

Append to a file named AGENT_ISSUES.md at the root of the project you're currently working in — the directory holding the README / package manifest / .git. If you genuinely can't identify a project root, use the current working directory. Use the same file for the entire session so all entries collect in one place.

If the file doesn't exist yet, create it with this header first, then add your entry:

# Agent Issue Log

Problems and bugs recorded automatically by agents while using this project.
Each entry below is one issue: what was being attempted, what went wrong, and the
workaround used. Send this file back to the project author so they can fix and
improve things.

---

Entry format

Each issue is one section, appended to the end of the file. Use this exact template so the entries stay uniform and easy for the author to triage in bulk:

## [<YYYY-MM-DD HH:MM>] <one-line summary of the problem>

- **Severity:** blocker | major | minor | nit
- **Doing:** what you were trying to do, including the exact command/action if any
- **Symptom:** what actually happened — paste the key error text or wrong output
- **Workaround:** what you did to get past it, or "none — blocked" if you couldn't
- **Location:** the file / path / module / command involved (e.g. `scripts/setup.sh:42`)
- **Suggested fix:** a brief idea if you have one (optional — omit if you don't)

Get a real timestamp from the shell rather than guessing — e.g. run date '+%Y-%m-%d %H:%M' and use the result. Keep each field to a sentence or two; this is a triage note, not a report. Paste only the relevant lines of an error, not a whole stack trace, unless the stack trace is the point.

Severity guide — pick from the author's point of view:

• blocker — stops the project from being usable for its purpose; no reasonable workaround.
• major — important feature broken or docs badly wrong, but you found a workaround.
• minor — annoyance, small inconsistency, or unclear message that cost some time.
• nit — cosmetic or trivially-fixable (typo in output, slightly stale doc line).

How to log without derailing the task

Recording an issue should be a quick side-step, not a detour. The user asked for something else; keep doing that. When you hit a qualifying problem:

1. Append the entry (create the file with its header first if needed).
2. Mention it to the user in one short line — e.g. "(Logged the failing make build step to AGENT_ISSUES.md.)" — so they know it's being captured.
3. Continue with the original task using whatever workaround you found.

Don't ask the user for permission to log each issue, and don't pause the main task to investigate a bug more deeply than the task requires — note what you observed and move on. The author, not you, will do the deep fix later.

Example

After a documented setup command failed, the appended entry looks like:

## [2026-06-19 14:32] `pip install -r requirements.txt` fails on pinned numpy

- **Severity:** major
- **Doing:** Following README "Quickstart" step 2 to install dependencies.
- **Symptom:** Build error — `numpy==1.21.0` has no wheel for Python 3.12; pip tries to compile from source and fails on `longintrepr.h`.
- **Workaround:** Installed `numpy>=1.26` instead; the rest of the project ran fine against it.
- **Location:** `requirements.txt:3`, README "Quickstart" step 2
- **Suggested fix:** Loosen the numpy pin or document a supported Python version.

One section, self-contained, immediately actionable for the author — that's the bar for every entry.