fix-markdown

name	fix-markdown
description	Fix lint, formatting, and prose issues in markdown files using Prettier and Vale. Use when the user or agent needs to fix lint, formatting, and prose issues in markdown files.

Agent protocol: Fix markdown file

GOAL: use prettier and vale to fix lint, formatting, and prose issues in markdown files.

WHEN: use when the user or agent needs to fix lint, formatting, or improve prose in markdown files.

NOTE: strictly follow E-Prime directive (avoid "to be" verbs) when writing or correcting prose.

References

The following reference files serve as strict guidelines when updating prose.

Locate the reference files in the references folder.

• references/e-prime-directive.md: The E-Prime Communication Protocol defining the rules for avoiding to be verbs.

Primary directives

Formatting and linting sequence

• Format first & last: Always run prettier before analysis and after edits
• E-Prime compliance: Strictly follow references/e-prime-directive.md when writing/correcting prose
• Vale cycle: Run vale iteratively (lint → fix → verify) until no issues remain
• Research complex issues: Use search tools or Perplexity for unfamiliar lint problems

Tool commands

• Format: prettier --write <file_path>
• Sync rules: vale sync
• Lint: vale --no-wrap --output=JSON <file_path>

Vale fixing guidelines

• Path wrapping: Wrap filenames, URIs, URLs, and paths in backticks
• Context awareness: Check line numbers - issues may appear as substrings in technical terms
• False positives: Wrap acronyms, names, and proper nouns in backticks
• Headings: Use sentence case (capitalize first character only)
• Passive voice: Follow E-Prime directive to remove "to be" verbs
• Follow hints: Use Vale's issue links when needed

Efficiency directives

• Batch operations on file groups, avoid individual file processing
• Use parallel execution when possible
• Target only requested files
• Reduce token usage in all operations

Task management

For complex tasks: use todo system to break down, plan, and optimize workflow.

Workflow

• Run vale sync to update lint rules
• Run prettier --write for baseline formatting
• Study file and apply Vale path directives (wrap all paths/filenames in backticks)
• Iteratively run vale, fix issues, and verify until no issues remain
• Run prettier --write for final formatting
• DONE

Output

Files modified:

• Target markdown files - Formatted and lint-free

Status communication:

• Reports number of issues fixed
• Confirms Vale shows zero remaining issues
• Lists file paths processed