tools-report-markdown

name

tools-report-markdown

description

Produce and validate architecture-review report and plan artifacts: Markdown, YAML frontmatter, Mermaid diagrams, jq/yq checks, Graphviz/D2 graphs, links, spelling, and format. Use when writing or checking cited reports, system-map diagrams, score summaries, or refactoring plans. This is report-quality evidence, not architecture evidence. NOT for gathering findings (use tools-code-search, tools-codegraph, tools-ast-grep, tools-lsp-tree-sitter, language, and operational tool skills).

Report and Markdown tools

The report is an artifact a human reads and a tool re-parses. These tools keep its frontmatter machine-valid and its diagrams renderable, and they catch broken links and typos before the report ships.

Evidence dimension: report (quality of the artifact, not the architecture).

When to use

Use during the write-the-report step and before declaring a report or plan done. First decide the audience:

• Human-facing reports: consider a small Mermaid diagram for the system map, dependency clusters, or boundary drift when it improves comprehension.
• AI/agent-targeted reports: prefer plain text adjacency lists, cited bullets, and compact structure. Do not spend tokens on fancy diagrams, broad tables, or formatting polish; models do not read diagrams as evidence.

Use to validate YAML frontmatter parses, render human-facing diagrams when chosen, and check links/spelling. Scope checks to the target report or plan; broaden to repo-wide docs only when the user asks. Diagrams are summaries for people, not architecture evidence.

Commands

Use the repo's detected package runner for Node-based formatters. The example uses npm exec; substitute pnpm exec, bunx, or the configured script when that is the project runner.

# Validate report frontmatter with the authoritative helper
architect-validate-report report.md

# Extract frontmatter for quick local jq/yq checks
python -c 'from pathlib import Path; print(Path("report.md").read_text().split("---", 2)[1])' > /tmp/report-frontmatter.yaml
yq -o=json '.' /tmp/report-frontmatter.yaml | jq '.tool_coverage'

# Optional for human-facing reports: render a Mermaid diagram to SVG
mmdc -i map.mmd -o map.svg

# Graphviz / D2 for graphs produced by pydeps, goda, go-callvis
dot -Tsvg graph.dot -o graph.svg
d2 graph.d2 graph.svg

# Link check (catches dead evidence refs and doc links)
lychee report.md

# Spelling (technical dictionary as needed)
codespell report.md

# Format check for the target artifact(s), using the repo's package runner
npm exec -- prettier --check report.md

The authoritative frontmatter/section validation is architect-validate-report — these CLIs are for quick local checks and diagram rendering, not a replacement for it.

Evidence output

Record:

• dimension: report.
• source: validation/render/link/spell command and artifact path.
• facts: parsed frontmatter, optional rendered diagrams, valid links, or reported failures.
• limits: skipped cosmetic checks, missing renderer, or dropped diagrams.

Confidence impact

This dimension does not affect architecture scores. A beautiful report with thin evidence is still low confidence; a plain report with strong evidence is high. Report tooling guards readability and machine-parseability only — never let Mermaid, tables, or formatting polish stand in for evidence coverage.

Failure and missing-tool handling

• Tool missing → skip the cosmetic check (record tools_skipped for the report dimension); it does not block a valid report. Frontmatter validity is the one thing that matters — if yq/the helper can't parse it, fix the frontmatter before shipping.
• mmdc/dot failing to render → the diagram source is malformed; fix it or drop the diagram. A broken diagram is worse than none.

When to stop

Validate frontmatter. For human-facing reports, render at most the one or two Mermaid diagrams the report needs. For AI-targeted reports, skip diagrams and use plain text. Run scoped link and spell passes on the target artifact. Stop there — don't generate a gallery of diagrams, run repo-wide format sweeps, or chase stylistic lint that doesn't change comprehension. Report tooling is the last mile, not a place to spend the evidence budget.

Hard rules

• Frontmatter must parse; everything else here is optional polish.
• Mermaid diagrams are optional and human-facing; plain text is preferred for AI-targeted reports.
• Diagrams summarize evidence — they never substitute for cited refs.
• Report quality never raises an architecture score or its confidence.
• Use the CLIs; the authoritative schema check is architect-validate-report.