Dev Error Notebook

dev-error-notebook is a small agent-first skill for turning solved problems into reusable notes. It helps an agent decide what is worth recording, where to record it, and how to find it again later.

It is platform-neutral: you can use the protocol with Codex, Claude, or any other agent system that can read instructions and files.

Quick Start

npx skills add Air000000/dev-error-notebook --skill dev-error-notebook -g

1. Put this skill where your agent can read it.
2. Use it after a fix, confirmed workaround, regression, or reusable troubleshooting session.
3. On first use, let the agent initialize the project notebook structure if it does not already exist.

Default runtime notebook structure:

• index.json
• references/categories/

Optional:

• taxonomy.json for project-specific category names
• ERROR_NOTEBOOK.md for a human-readable mirror

Out of the box, the skill can work without taxonomy.json. The agent will still classify incidents using the default rules in SKILL.md.

What The Agent Does

The workflow is simple:

1. Extract facts from the issue.
2. Decide incident, variant, or skip.
3. Read index.json.
4. Read taxonomy.json if it exists.
5. Read only the top 1-2 matching category files.
6. Dedupe using title, error signature, and component paths.
7. Write the result and update index metadata.

Source of truth:

• index.json
• references/categories/category-*.md

Optional file:

• ERROR_NOTEBOOK.md It is only a human-readable mirror or landing page. It is not required and is not the source of truth.

Files

• SKILL.md Main protocol: write gate, naming rules, dedupe logic, retrieval limits, and output format.

• assets/error-entry-template.md Canonical note template.

• assets/taxonomy-profile-template.json Starter template for a project-specific taxonomy config.

• evals/evals.json Example eval prompts for routing, dedupe, skip logic, and fallback behavior.

Taxonomy

taxonomy.json is optional.

Without it:

• the agent still works
• the agent creates or reuses categories using the default mechanism-first rules

With it:

• category names become more consistent for your project
• you can define preferred categories and keyword aliases

What you can customize:

• preferred category names
• keyword aliases
• dynamic category rules
• domain wording

What should usually stay stable:

• incident | variant | skip
• naming rules
• dedupe triad
• mechanism-first classification

If your field is not covered by the included examples, change the taxonomy config rather than rewriting the whole protocol.

Updates

See CHANGELOG.md.