dev-error-notebook

name	dev-error-notebook
description	Maintain a reusable engineering error notebook with explicit write gating, mechanism-first category routing, dedupe, and selective retrieval. Use when a bug is fixed, a stable workaround succeeds, a regression recurs, or troubleshooting knowledge should be written back for future reuse.

Dev Error Notebook

Purpose

Turn one-off debugging into reusable engineering memory without forcing every write into a rigid script.

This skill defines a hybrid protocol:

• the model makes judgment-heavy decisions
• helper tooling may enforce deterministic mechanics such as ids, validation, and index sync

Storage Contract

Primary agent-facing artifacts:

• Project index: .github/skills/<project-debug-notebook>/index.json
• Category modules: .github/skills/<project-debug-notebook>/references/categories/category-<category-slug>.md

Optional artifacts:

• Taxonomy config: .github/skills/<project-debug-notebook>/taxonomy.json
• Human portal: ERROR_NOTEBOOK.md

Default operating mode is agent-first:

• route from index.json
• read and write category modules as the source of truth
• use taxonomy.json when present to guide category selection

If no project index exists, fall back to a single local notebook file using the same schema and naming rules.

Responsibilities

Model responsibilities:

• decide incident | variant | skip
• choose the best category or justify a new one
• write the human-meaningful fields
• decide whether a new case shares the same underlying failure mechanism as a prior case

Helper responsibilities:

• generate entry_id
• validate required fields
• normalize category/file naming
• compare dedupe candidates using structured fields
• update index.json
• optionally sync a portal if one exists

Trigger Guidance

Use this skill when:

• a fix is complete and should be captured
• a stable workaround is confirmed and worth reusing
• a regression is identified and should be compared against prior incidents
• a recurring issue appears and prior notes may help
• a failed attempt reveals a reusable anti-pattern
• the user asks for a postmortem, RCA, incident note, prevention checklist, or reusable troubleshooting note

Mandatory Write Gate

Decide one outcome before any write:

• incident: new confirmed issue with a reusable fix or stable workaround
• variant: same root-cause mechanism as an existing entry, but different environment, version, platform, or operating context
• skip: not suitable for durable notebook storage

Write a new incident only when all are true:

• the symptom or error signal is concrete
• the trigger or affected area is identifiable
• the fix or workaround has been verified
• at least one reusable quick check or prevention rule can be stated

Prefer writing when any are true:

• the issue repeated or is likely to repeat
• debugging took meaningful effort
• the root cause was non-obvious or easy to misdiagnose
• the issue affects build, CI, install, runtime, packaging, or core UI behavior

Use skip when any are true:

• root cause is not confirmed
• fix is not verified
• the issue is likely one-off noise or a transient with no reusable lesson
• the note would expose secrets, machine-local credentials, or sensitive non-shareable detail

Naming Rules

Entry id:

• format: <category-slug>-<yyyymmdd>-<nnn>
• keep compatibility with existing ids such as ui-interaction-20260324-001

Category slug:

• lowercase kebab-case
• 2-4 words
• describe the failure mechanism, not a person, page, or date
• examples: env-toolchain, build-ci, ui-interaction, api-contract, state-sync, network-installation

Category file:

• format: references/categories/category-<category-slug>.md

Title:

• format: <surface symptom> due to <root-cause mechanism>
• prefer searchable wording over short internal jargon
• include component or context only if it materially improves retrieval

Tags:

• use 4-8 tags
• mix mechanism, technology, and platform when helpful

Configurable Taxonomy

When taxonomy.json exists, treat it as the preferred category vocabulary and routing hint layer.

Taxonomy config should define:

• profile_name
• domain
• category_strategy
• preferred_categories
• keyword_aliases
• dynamic_category_rules

Use taxonomy config this way:

1. prefer configured categories before inventing a new one
2. map issue language through keyword_aliases
3. allow dynamic categories only when existing configured categories do not fit
4. keep the mechanism-first naming rule even when the domain changes

This keeps the core protocol stable across domains such as:

• software engineering
• research workflows
• data pipelines
• prompt and agent operations

Dedupe and Variant Rules

Use title + error signature + component paths as the first dedupe triad.

Append a variant only if all are true:

• same symptom family
• same root-cause mechanism
• same or adjacent component area

If wording is similar but the causal mechanism differs, create a new incident.

Entry Schema

Use the template in assets/error-entry-template.md.

Required fields:

• Entry ID
• Date
• Title
• Symptom
• Error Signature
• Component Paths
• Impact
• Root Cause
• Failed Attempts
• Final Fix
• Verification
• Quick Check
• Prevention Rules
• Tags
• Fix Fingerprint

Optional fields:

• References
• Severity
• Environment

Variant notes:

• start each variant note with a date and a one-line delta summary
• append environment-specific deltas, not a duplicate full incident
• if variants sprawl beyond a few bullets, create a separate incident instead

Workflow

1. Extract facts from the current issue.
2. Decide incident | variant | skip.
3. Read project index.json first when available.
4. Read taxonomy.json when available and use it to guide category ranking.
5. Rank categories and read only the top 1-2 category modules.
6. Run dedupe against candidate entries.
7. Choose append-variant | create-new | skip.
8. Write or update the notebook content.
9. Sync index metadata and optional portal navigation.
10. Return a structured writeback result.

Retrieval Pattern

When a new issue appears:

1. Read the index first.
2. Load taxonomy config when available.
3. Rank candidate categories by taxonomy hints, keywords, component paths, and prior fit.
4. Read top 1-2 category modules only.
5. If a strong match exists, propose the previous fix path first.
6. If no match exists, create a new category or entry only after resolution.

Output Format

When invoked, return:

• Writeback status: written | updated-variant | skipped-with-reason
• Target category
• Category reason
• Dedupe match
• Entry id
• Quick-check command
• Prevention rule
• Files updated

Quality Bar

An entry is complete only if another engineer can:

• recognize the issue signal
• apply the fix or workaround
• run verification
• reuse the note without needing the original debugging session