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
- Before final ready status, create or update
docs/fixes/YYYY-MM-DD-<slug>.md.
- Use the current local date for
YYYY-MM-DD.
- Use a lowercase slug with letters, numbers, and hyphens.
- Record what changed, why it changed, validation that actually ran, and follow-ups.
- Do not invent validation. If a check was skipped or blocked, say why.
- Follow
CLAUDE.md's Follow-up Tracking (MANDATORY) rule: never create GitHub issues for an
implementation that has not merged into main. Fix required work in the active PR or stack and
keep remaining tasks in its PRD or task list. The Follow-ups section may link to that document;
an issue number is not required. Only for already-merged features, track genuinely deferred work
in a GitHub issue and link it by number.
- Triage every candidate follow-up by origin before writing the Follow-ups section:
- Introduced by this PR or its stack (a regression, gap, inconsistency or stale artifact such as a cast or
snapshot that the change itself caused): fix it in the same PR. It is not a follow-up, and it never becomes
an issue.
- Pre-existing in an already-merged feature (reproduces on the base branch or a released version): ask the user, per item, whether to
fix it now or open a GitHub issue. Never open an issue without that per-item answer.
- Intended behavior (the code does what it was designed to do, but it surprised someone): document it
where users will look; it is neither a fix nor a follow-up.
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).
1---2name: fix-log3description: "Use when implementing, finishing, documenting, or reviewing a fix, repair, remediation, bug fix, debug-and-fix task, workflow fix, infrastructure fix, or any change that should leave a durable fix record under docs/fixes."4metadata:5 source: https://skillmd.com/skills/cloudposse/fix-log6 copyright: Copyright Cloud Posse, LLC 20267 version: "1.0.0"8---910# Fix Documentation1112Every implemented fix must leave a short Markdown record in `docs/fixes/`.1314`docs/fixes/` already contains 90+ pre-existing records in an older, inconsistent format (some with a15`# Fix: <title>` heading, some without; some with a `**Date:**` line, some without; and 25+ different ad hoc16`## ` section names across the set — `## Problem`, `## Root Cause`, `## Tests`, `## Related`, etc.). **Do not17migrate those** — they stay as-is. All new records use the merged format below, which keeps the old18convention's most useful, scannable elements (the `# Fix:` heading, the explicit `**Date:**` line) and adopts19a single, consistent five-section structure instead of ad hoc headers.2021## Workflow22231. Before final ready status, create or update `docs/fixes/YYYY-MM-DD-<slug>.md`.242. Use the current local date for `YYYY-MM-DD`.253. Use a lowercase slug with letters, numbers, and hyphens.264. Record what changed, why it changed, validation that actually ran, and follow-ups.275. Do not invent validation. If a check was skipped or blocked, say why.286. Follow `CLAUDE.md`'s **Follow-up Tracking (MANDATORY)** rule: **never create GitHub issues for an29 implementation that has not merged into `main`.** Fix required work in the active PR or stack and30 keep remaining tasks in its PRD or task list. The Follow-ups section may link to that document;31 an issue number is not required. Only for already-merged features, track genuinely deferred work32 in a GitHub issue and link it by number.337. Triage every candidate follow-up by origin before writing the Follow-ups section:34 - **Introduced by this PR or its stack** (a regression, gap, inconsistency or stale artifact such as a cast or35 snapshot that the change itself caused): fix it in the same PR. It is not a follow-up, and it never becomes36 an issue.37 - **Pre-existing in an already-merged feature** (reproduces on the base branch or a released version): ask the user, per item, whether to38 fix it now or open a GitHub issue. Never open an issue without that per-item answer.39 - **Intended behavior** (the code does what it was designed to do, but it surprised someone): document it40 where users will look; it is neither a fix nor a follow-up.4142## Required Document Shape4344```markdown45# Fix: <Title>4647**Date:** YYYY-MM-DD4849## Summary5051## Context5253## Changes5455## Validation5657## Follow-ups58```5960- `<Title>` is a short human-readable description of the fix (inline code spans are fine, e.g.61 `` # Fix: `describe affected` now checks `source` and `provision` sections ``).62- `**Date:**` restates the filename's date for at-a-glance scanning; keep it in sync with the filename.63- Use `None.` in `Follow-ups` only when no follow-up is known.6465## Validation6667After creating or updating fix docs, run:6869```bash70bash .claude/skills/fix-log/scripts/validate-fix-doc.sh docs/fixes/*.md71```7273The validator only checks the five required `## ` sections and the filename shape — it doesn't (yet) enforce74the `# Fix:` heading or `**Date:**` line. Run it against the files you're adding, not the whole directory75indiscriminately (it will report errors against the old-format records, which is expected and not something76to fix).