Error Journal Pro

Debugging the same error twice is a waste of engineering resources. This skill implements a durable error journaling system that ensures every difficult fix is recorded, searchable, and reusable. It moves beyond ephemeral logs by capturing the developer context, the verbatim error signature, and the specific resolution that actually worked.

What it does

• Standardized Logging records verbatim error messages, stack traces, and environmental context into a central markdown file.
• Signature Tracking prevents duplicate entries by collapsing whitespace and normalizing error messages into unique signatures with occurrence counts.
• Semantic Search allows developers to query the journal by error code, function name, or partial message before starting a new debug session.
• Resolution Archiving maps successful fixes to specific commits or PRs, providing a direct link between the failure and the solution.
• Secret Redaction enforces a workflow for removing tokens, cookies, and connection strings from logs before they hit the repository.

How it works

1. Search the journal using a fragment of the error message to see if the team has encountered and solved this specific issue before.
2. Log new errors immediately using the add command, capturing the verbatim stack trace and current task context.
3. Resolve entries once a fix is found, appending the resolution details and referencing the relevant commit ID.
4. Audit the journal periodically to identify high-frequency failures that require systemic architectural changes rather than one-off fixes.

Frameworks & tools

This tool uses a bash script (error-journal.sh) to manage a plain Markdown file (docs/error-journal.md). It relies on standard Unix utilities like grep and sed for search and entry management, making it compatible with any repository structure.

Why this beats prompting it yourself

Generic AI prompts often paraphrase errors or suggest generic fixes that ignore your specific codebase history. This skill enforces a strict data schema and signature-matching logic that turns your repository into a self-documenting knowledge base. It ensures that tribal knowledge about complex bugs is captured in a format that both humans and LLMs can query reliably.

Use cases

• Recording the fix for an intermittent race condition that only appears in CI environments.
• Onboarding new developers by providing a searchable history of common environment setup pitfalls.
• Tracking the recurrence of specific API failures following a major middleware refactor.
• Documenting "won't fix" edge cases with detailed explanations of why they occur.

Known limitations

Requires manual invocation to log or resolve errors; it does not automatically scrape system logs. The signature matching may fail if error messages contain unique IDs or timestamps that aren't manually redacted.