Summary
Running mdtablefix --wrap --renumber --breaks --ellipsis --fences --in-place across Podbot rewrites ordinary prose paragraphs and list items in many files that contain no table change. This creates large unrelated diffs when the formatter is used for documentation housekeeping.
Reproduction
From leynos/podbot on branch feat/syncagentdocs at commit 337860e:
fd --print0 --type f --extension md --extension markdown --extension mdx . \
| xargs -0 mdtablefix --wrap --renumber --breaks --ellipsis --fences --in-place
git diff --stat
Observed diff summary included 39 modified Markdown files and hundreds of insertions/deletions, even though the intended change only touched repository guidance documents.
Representative examples:
docs/developers-guide.md: prose paragraphs under "Security audit ignores" and later testing guidance were reflowed.docs/execplans/2-6-2-runtime-denylist.md: opening ExecPlan boilerplate and decision-log paragraphs were reflowed.docs/complexity-antipatterns-and-refactoring-strategies.md: normal explanatory prose was reflowed.docs/rstest-bdd-users-guide.md: ordinary paragraphs and numbered-list items were reflowed.
Example transformation:
-This ExecPlan (execution plan) is a living document. The sections
-`Constraints`, `Tolerances`, `Risks`, `Progress`, `Surprises and discoveries`,
-`Decision log`, and `Outcomes and retrospective` must be kept up to date as
-work proceeds.
+This ExecPlan (execution plan) is a living document. The sections `Constraints`,
+`Tolerances`, `Risks`, `Progress`, `Surprises and discoveries`,
+`Decision log`, and `Outcomes and retrospective` must be kept up to date as
+work proceeds.
Expected behaviour
mdtablefix should keep its default write scope to tables, or provide a mode where only tables are changed. If --wrap intentionally rewrites prose, that behaviour should be opt-in separately from table formatting and should preserve existing clean wrapping where no table needs repair.
Actual behaviour
The formatter rewrites prose, list items, and ExecPlan boilerplate across unrelated files. The resulting diff is too noisy to review safely and makes it hard to distinguish intentional documentation edits from formatter churn.
Impact
Podbot's make fmt target invokes mdtablefix before Markdown linting. A documentation-only change can therefore produce broad unrelated diffs, which then have to be manually reverted before review.
Summary
Running
mdtablefix --wrap --renumber --breaks --ellipsis --fences --in-placeacross Podbot rewrites ordinary prose paragraphs and list items in many files that contain no table change. This creates large unrelated diffs when the formatter is used for documentation housekeeping.Reproduction
From
leynos/podboton branchfeat/syncagentdocsat commit337860e:Observed diff summary included 39 modified Markdown files and hundreds of insertions/deletions, even though the intended change only touched repository guidance documents.
Representative examples:
docs/developers-guide.md: prose paragraphs under "Security audit ignores" and later testing guidance were reflowed.docs/execplans/2-6-2-runtime-denylist.md: opening ExecPlan boilerplate and decision-log paragraphs were reflowed.docs/complexity-antipatterns-and-refactoring-strategies.md: normal explanatory prose was reflowed.docs/rstest-bdd-users-guide.md: ordinary paragraphs and numbered-list items were reflowed.Example transformation:
Expected behaviour
mdtablefixshould keep its default write scope to tables, or provide a mode where only tables are changed. If--wrapintentionally rewrites prose, that behaviour should be opt-in separately from table formatting and should preserve existing clean wrapping where no table needs repair.Actual behaviour
The formatter rewrites prose, list items, and ExecPlan boilerplate across unrelated files. The resulting diff is too noisy to review safely and makes it hard to distinguish intentional documentation edits from formatter churn.
Impact
Podbot's
make fmttarget invokesmdtablefixbefore Markdown linting. A documentation-only change can therefore produce broad unrelated diffs, which then have to be manually reverted before review.