Brain-Fix

Single responsibility

You receive ONE lint finding (file, kind, message, fixHint). Open the file, apply the single minimal edit that clears THAT finding, then stop. Never touch other files. Never broaden scope.

If the fix is genuinely ambiguous (e.g. a broken link with no unambiguous target), make NO edit and explain why.

Contract

• You will be given: file (absolute path), kind (the check slug), message (the lint finding text), and optionally fixHint (a concrete suggestion for the repair).
• Read the file first, then apply the ONE targeted edit.
• Do not restructure sections, rewrite prose, or clean up unrelated issues.
• Do not create new files.
• After the edit, stop — the caller will re-lint to verify.
• Drain-mode gate (W7-B2, orch-01): when you run inside drain-to-green, the caller enforces a structural-only rule in code — frontmatter, link-target, and index-page edits land directly; any change to body PROSE is reverted and parked as a kb-cleanup draft the operator approves with a diff. Prefer the smallest structural repair; if only a prose rewrite can clear the finding, make your best single proposal knowing it becomes a reviewable draft, never a silent edit.

Per-kind guidance

frontmatter.missing-field

The frontmatter is missing a required field (title, description, or category — a missing date field is auto-fixed upstream and never reaches this skill). Add the missing field to the YAML front-matter block between the --- delimiters. Choose pattern, antipattern, decision, operation, or reference as appropriate for category.

frontmatter.unparseable

The YAML frontmatter cannot be parsed. Look for syntax errors: unquoted colons in values, inconsistent indentation, or malformed arrays. Fix the minimum change to make the frontmatter valid YAML. If the block is entirely absent, add a minimal valid block at the top of the file.

links.broken

A markdown link [text](path) points to a file that does not exist. If the fixHint gives an unambiguous replacement path, update the link. If no clear target exists, remove the link and replace it with plain text. Do not guess at a target.

links.broken-wikilink

A wikilink [[slug]] references a file that cannot be resolved. If the fixHint gives an unambiguous replacement slug, update it. Otherwise remove the wikilink and replace it with plain text. Do not guess.

length.hard-cap

The file exceeds the hard line-count limit. This requires significant pruning. Summarise or remove the least essential sections. Prefer removing duplicate content, over-long examples, or verbose prose. Keep all load-bearing facts.

length.soft-cap

The file exceeds the soft line-count limit. Lightly trim: shorten verbose sections, remove redundant examples, or consolidate related bullet points. Do not remove factual content.

index.missing

A required category index file is missing. Do not create new files — this kind requires operator action. Make no edit and explain that the index file must be created by the operator.