/page-report

name: page-report
description: Shared report-page contract for Agentic SEO modules that render editable, human-first Markdown reports in the Web Companion.
metadata:
  version: 1.0.0
  category: contract

Page Report

Use this skill whenever an Agentic SEO workflow generates a report page for the Web Companion. It is a shared contract, not a standalone SEO module.

When To Use

Use `page-report` from report-producing skills and runtime code when creating or reviewing `report.md` for Technical SEO, Internal Links, SEO Analysis, Keyword Research, SERP Extract, Backlink Analysis, Topic Cluster, E-E-A-T, or Competitive Analysis.

Do not use this skill for public content drafts, approval handoffs, inline chat answers, raw provider captures, or authorial Brain updates that are not report pages.

Critical Points

• The canonical report path is `project/analyses/<module>/<run-slug>/report.md`.
• The report is the editable human presentation layer. Raw evidence, normalized YAML/JSON, logs, and operational artifacts stay in `sources/`, `audits/`, `keywords/`, `clusters/`, `eeat/`, or `workbench/`.
• Frontmatter must include `title`, `slug`, `report_type`, `generated_at`, `status`, `source_artifact`, and `summary`; include `score` only when the module has a real score.
• Do not write `# <title>` in the Markdown body. The Companion renders the title from frontmatter.
• Use the project language from `project/.agentic-seo/project.json.language` unless a command has an explicit language override. Complete copy is required for `pt-BR` and `en`.
• New visual fences must be YAML with `version: 1`: `agentic-kpis`, `agentic-chart`, and `agentic-table`. JSON fences are legacy read compatibility only.
• Tables must use stable lower-snake ASCII `key` values. User-facing `label` values may be translated or edited without changing keys.
• Calculation tables must mark columns with `role: weight`, `role: points`, and `role: loss` so score recalculation survives label edits.
• Each report-producing module has `skills/<module>/contract.yaml` and `templates/analyses/<module>/report-skeleton.md`; keep required H2 sections and table keys from the skeleton.
• Before declaring a manual report done, run `npm run validate:reports -- --module=<module> --slug=<run-slug>` or use `scripts/lib/report-writer.mjs`, which refuses invalid reports before writing.
• Never paste raw provider JSON, object arrays, `[object Object]`, internal IDs, or snake_case evidence into the visual body. Convert evidence into natural language and readable tables.
• Format numbers per the project language. The canonical source is `shared/locale.mjs` (`getProjectLanguage`, `formatNumber`, `formatPercent`, `canonicalKeyword`). Skills either ship locale-formatted strings in `agentic-table`/`agentic-kpis` cells, or leave numbers raw for the Companion (`useI18n().formatNumber` / `formatPercent`) to format on render. Percent-bearing columns use the `_pct` key suffix on the 0..100 scale.
• Always return `report_md` and `browser_prompt: { recommended: true, message: "Posso abrir o Web Companion para você ver a análise?", open_with: "project-browser" }`.
• Register the generated report in `project/brain/log.md` as `type: decision` unless a more specific log type is required.

Framework

1. Build The Source Artifact

Write the module's authoritative machine-readable artifact first. It may be YAML or JSON, but it must remain outside `project/analyses/` and be referenced by frontmatter `source_artifact`.

2. Render The Human Page

Start with an executive reading. Then add module-specific sections, visual blocks, and human-readable appendices. Keep technical depth, but translate it into prose, friendly labels, and compact evidence.

3. Validate The Contract

Before returning the result, verify: canonical path, frontmatter, no H1 body title, no HTML default, YAML visual fences, no raw JSON/object dumps, readable evidence, source separation, and log entry.

4. Review The Result

For QA, generate one report per module with fixtures/offline data. A report is satisfactory only when it scores at least 4/5 for clarity, evidence separation, visual usefulness, actionability, and localization, with no category below 3/5.

Output Format

The report Markdown must have this shape:

---
title: "Human report title"
slug: "stable-run-slug"
report_type: "technical-seo"
generated_at: "2026-05-23T00:00:00.000Z"
status: "ready"
source_artifact: "audits/example/report.yaml"
summary: "One-sentence executive summary."
score: "92"
---

Executive summary prose without a duplicate H1.

```agentic-kpis
version: 1
items:
  - label: Score
    value: 92/100

Use only supported `report_type` values: `technical-seo`, `internal-links`, `seo-analysis`, `keyword-research`, `serp-extract`, `backlink-analysis`, `topic-cluster`, `eeat`, and `competitive-analysis`.

## Done Criteria

- `report.md` exists under the canonical module path and is returned as `report_md`.
- `source_artifact` points to the normalized technical source.
- The Companion can list, open, edit, save, and roundtrip the page.
- Visual fences parse as YAML `version: 1`.
- No visible JSON/object dumps or duplicated title appear in the report body.
- The report is registered in `brain/log.md`.