Env Tool Log

Usage Workflow

1. Initial Check
   • Before using a tool for the first time in a session, read the corresponding tool section of the shared

     lessons.md

     ; if there are no relevant records, use the tool normally. The scope includes shell, file reading, search, patch editing, browser, and MCP.
   • For shell commands, also consult the relevant command rules; invoke built-in tools according to their own schemas and confirmed experience rather than forcing shell rules onto them.
   • Reading the index and maintaining the log do not recursively trigger the initial check. When switching environments or encountering unexpected errors, recheck the relevant experience.
   • Run

     fail_log.py query "keyword" --all --limit 5

     using command or error keywords; review both OPEN unresolved issues and FIXED solutions, and do not treat unrelated matches as the current cause.
   • View only the environment snapshot for the relevant tool. If it is missing, stale, or the environment has changed, probe it again according to the snapshot rules.
2. Execution and Reuse
   • Reuse confirmed paths, versions, and rules within the same session. If the environment has not changed, do not repeat reads or probes.
   • Continue using the configured

     ENV_TOOL_LOG_DIR

     data directory, or the default directory when it is not configured. If permissions require a temporary override, explain the reason, the original directory, and the alternative directory; keep subsequent calls consistent.
   • A failure to read logs or snapshots must not block unrelated work. Do not silently switch directories and accumulate records elsewhere.
3. Failures and Closure
   • Promptly record stable signatures, known causes, and solutions for reusable tool, parameter, or environment failures.
   • Reuse the original signature for the same error class. Update the occurrence count, most recent time, and current status rather than adding a new record for each recurrence.
   • A signature should use the tool and stable error characteristics, excluding dynamic paths, timestamps, and waybill or order numbers. Do not merge different causes based on vague text similarity.
   • Leave the cause empty or mark it as pending confirmation when it is unknown. Do not present a guess as fact.
   • After a fix passes a retry, run

     mark-fixed

     for the same signature and record the verified method.
   • Keep the issue OPEN when there is only a candidate solution or partial validation, and describe the validation scope.
   • Closing an issue does not delete its preventive rules. When it recurs, retain the previously verified method, mark it as pending review, and correct it in place after confirmation.

   • add

     and

     mark-fixed

     automatically update the tool-categorized lessons index while preserving manually written content. When the cause, solution, or applicable scope changes, update the original entry rather than appending a new lesson for each round.
   • Keep expected TDD red lights, normal searches with no matches, and business assertion failures in task validation. Record a corresponding tool failure only when a tool cannot execute tests normally.
   • If the logging script itself fails, correct the invocation directly rather than recursively invoking it to register the failure. If it remains unavailable, document the gap in the task and do not let the logging process block authorized work.

Data and Scripts

~/.my-skills/env-tool-log/

ENV_TOOL_LOG_DIR

from

add

--from codex/cc/pi

.codex

• Lessons Index:

  lessons.md

  lists stable signatures, trigger conditions, and current practices by tool, linked to records with the same signature in the logs. Do not truncate the complete index to only the most recent entries, and do not let summaries injected by hooks replace the relevant sections.
• Failure Log:

  scripts/fail_log.py

  supports recording, querying, closing, archiving, and generating lessons. See Data and Usage for parameters, categories, and client hooks.
• Environment Snapshots:

  scripts/snapshot_env.py

  probes tool paths and versions on demand. See Environment Snapshots for refresh timing and fields.
• Client Hooks: The Claude Code installation script uses them as needed and does not automatically install them or modify client configuration. Automatically captured records still require confirmation that the failure was expected and must be closed after the actual fix.

Cross-Harness Integration

Before using the shell or a built-in tool, read the relevant section of the shared env-tool-log lessons index on the tool's first use in the session. Reuse it after it has been read if the environment has not changed. Register unexpected tool errors using a stable signature, update the same error class in place, close records after fixes are verified, and retain preventive rules.