tools-report-markdown

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