document-issues

Append structured markdown entries to a session issues.md log.

108|37|Updated Apr 25, 2025
One-click install
npx skills add https://github.com/goodfire-ai/causalab --skill document-issues
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: document-issues
Source: https://github.com/goodfire-ai/causalab/tree/main/.claude/skills/document-issues
Command: npx skills add https://github.com/goodfire-ai/causalab --skill document-issues

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It prevents repeated pain by turning failures, confusions, odd results, and workarounds encountered during work into a persistent, session-level record that future agents can learn from.

Core Features & Use Cases

  • Proactive issues logging: Records errors, confusions, unexpected behavior, workarounds, and improvement suggestions as you encounter them.
  • Session-aware documentation: Writes to the active research session’s top-level issues.md using agent_logs/.current to resolve the correct directory.
  • Operational guardrails: Refuses to run when there is no valid active session marker (agent_logs/.current missing or stale), prompting you to start with /research-session.

Quick Start

Run /document-issues while you have an active research session so the skill updates agent_logs/<SESSION_NAME>/issues.md with what went wrong and how you worked around it.

Frequently Asked Questions about document-issues

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I log debugging issues and workarounds for agent sessions?

To log debugging issues and workarounds, run the command during an active research session. It appends structured markdown entries to the session's issues.md file, capturing failures, oddities, and fixes for future agents to reference.

What is the best way to keep a persistent record of environment problems during research workflows?

A persistent record of environment problems is maintained by writing structured markdown logs into an active session directory. This approach proactively captures errors and unexpected behavior, preventing repeated debugging pain across future agent runs.

How do I document unexpected behavior and fixes into a markdown issues log?

You document unexpected behavior by appending categorized markdown entries to issues.md. The skill resolves the correct session directory using an active marker and records the failures, confusions, and workarounds encountered during your workflow.

Do I need an active research session marker to log agent workflow issues?

Yes, you need a valid agent session marker located at agent_logs/.current. The skill refuses to run if this marker is missing or stale, prompting you to start a research session first to ensure proper logging.

Why does my issues log command fail to run without a current session directory?

The issues log command fails because it requires a valid active session marker at agent_logs/.current to resolve the correct directory. Without it, the skill cannot determine where to append the structured markdown entries for your workarounds.

When should I not use a persistent issues log for debugging agent sessions?

You should not use a persistent issues log if you lack an active research session. The operational guardrails prevent execution when the agent_logs/.current marker is missing, ensuring entries are never written to incorrect or stale directories.