---
{"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).","name":"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.

```sh
# 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`.