Fix Log

Fix Documentation

Every implemented fix must leave a short Markdown record in docs/fixes/.

docs/fixes/ already contains 90+ pre-existing records in an older, inconsistent format (some with a # Fix: <title> heading, some without; some with a **Date:** line, some without; and 25+ different ad hoc ## section names across the set — ## Problem, ## Root Cause, ## Tests, ## Related, etc.). Do not migrate those — they stay as-is. All new records use the merged format below, which keeps the old convention's most useful, scannable elements (the # Fix: heading, the explicit **Date:** line) and adopts a single, consistent five-section structure instead of ad hoc headers.

Workflow

1. Before final ready status, create or update docs/fixes/YYYY-MM-DD-<slug>.md.
2. Use the current local date for YYYY-MM-DD.
3. Use a lowercase slug with letters, numbers, and hyphens.
4. Record what changed, why it changed, validation that actually ran, and follow-ups.
5. Do not invent validation. If a check was skipped or blocked, say why.
6. If the fix leaves any follow-up work (anything under Follow-ups other than None.), it must satisfy CLAUDE.md's Follow-up Tracking (MANDATORY) section: open a GitHub issue and link it by number (e.g. #1234) in the Follow-ups section. A Follow-ups entry like "a follow-up will..." with no issue number is incomplete — the work will never be tracked.

Required Document Shape

# Fix: <Title>

**Date:** YYYY-MM-DD

## Summary

## Context

## Changes

## Validation

## Follow-ups

• <Title> is a short human-readable description of the fix (inline code spans are fine, e.g. # Fix: `describe affected` now checks `source` and `provision` sections).
• **Date:** restates the filename's date for at-a-glance scanning; keep it in sync with the filename.
• Use None. in Follow-ups only when no follow-up is known.

Validation

After creating or updating fix docs, run:

bash .claude/skills/fix-log/scripts/validate-fix-doc.sh docs/fixes/*.md

The validator only checks the five required ## sections and the filename shape — it doesn't (yet) enforce the # Fix: heading or **Date:** line. Run it against the files you're adding, not the whole directory indiscriminately (it will report errors against the old-format records, which is expected and not something to fix).