# HTML Report Blueprint

This blueprint is for `.submissions/<change-slug>.html`.

## Structure

### Top navigation

- title
- quick metadata
- anchor links to each major section
- status badges (tests/lint/manual verification)

### Hero / summary band

Show the following at a glance:

- what was delivered
- why it matters
- files changed count
- validation status
- PR status/link

### Main sections

#### 1. Executive Summary

A short paragraph and 3-5 bullets.

#### 2. Scope of Change

A grouped table:

| Area | Files | Reason |
|------|-------|--------|
| Skill definition | ... | ... |
| Report generation | ... | ... |
| Supporting docs/templates | ... | ... |

#### 3. End-to-End Behavior

Describe the lifecycle from user request to draft PR + report artifact.
Use a flow diagram or numbered steps.

#### 4. Codebase Fit

Show where the touched files live in the repo and how they relate to any existing project conventions.

Useful visuals:

- impacted file tree
- simple architecture map
- responsibility table

#### 5. Key Implementation Details

For each important decision, include:

- what it does
- why it was done this way
- alternatives or tradeoffs

#### 6. Non-Obvious Code Explained

Use callout cards for subtle points such as:

- why a branch of logic exists
- why a path or convention is chosen
- how a generated artifact connects to the PR workflow

#### 7. Visual Evidence

Examples:

- screenshots
- GIF/video embeds
- terminal screenshots or code-block transcripts
- diagrams in SVG/Mermaid

When a visual cannot be obtained, add a short note and provide an equivalent diagram.

#### 8. Validation

Show a table like:

| Check | Command | Result | Notes |
|------|---------|--------|-------|

#### 9. Risks / Follow-Ups

Keep this honest and explicit.

#### 10. Appendix

- snippets
- commands
- environment/context notes

## Styling guidance

Aim for a polished engineering handoff document:

- neutral background
- card layout
- readable typography
- restrained accent color
- code blocks with contrast
- responsive layout
- print-friendly enough to export if needed

## Interaction guidance

Allowed light interactions:

- sticky table of contents
- collapsible details sections
- copy buttons for commands/code
- tabbed views if they reduce clutter

Do not hide core findings behind interaction; they should be visible by default.