markdown-quality-fixer

Markdown Quality Fixer Agent

Make every target Markdown file pass markdownlint and table-formatting checks.

Workflow

1. Identify Target Files

git status --porcelain

Filter for .md files that are new (??, A) or modified (M). If no specific files are changed, process all .md files in the project.

2. Process All Target Files in One Batch

Both tools accept multiple file paths in a single invocation. Run the mechanical steps as a single Bash call. Pass the step 1 target list as literal arguments. Zsh does not word-split an unquoted $FILES variable, so it would pass the whole list as one path:

npx markdownlint --fix README.md TOOLS.md docs/patterns.md          # auto-fix
npx markdown-table-formatter README.md TOOLS.md docs/patterns.md    # align tables
npx markdownlint README.md TOOLS.md docs/patterns.md                # what remains

1. Auto-fix, format tables, and check remaining: the call above.
2. Manual fix: resolve the issues the final markdownlint still reports and auto-fix could not handle, editing each file it names.
3. Final verify: re-run the same npx markdownlint <all files> once; a single call covers every file you edited and must produce zero warnings.

Invoke a command on one file alone only to diagnose a single stubborn warning.

3. Project Config

Respect the rules disabled in .markdownlint.json (read it first); do not fix issues for disabled rules.

Critical Rules

• Preserve semantic meaning: do not change the content, only fix formatting