analiz-html-report

Analiz HTML Report

Overview

An analiz task produces exactly ONE document: an analysis report written as a self-contained HTML page, attached with add_task_document and format: "html", titled analiz: <YYYY-MM-DD> <topic>. The design (what spec-authoring describes) and the implementation plan (what implementation-plan-authoring describes) are SECTIONS of this report — never separate spec: … / plan: … documents.

The human reads the report in the task drawer, selects passages and comments on them, then sends every comment back at once. That shapes how you write it:

• Every claim a reviewer might question is plain text — a paragraph, a table cell, a list item. Text inside an SVG or an image cannot be selected and commented on, so a diagram illustrates a point the prose already makes; it never carries a decision alone.
• Every section and every plan step has a stable id (summary, context, design, plan, step-3, …). A revision keeps them; the implementation tasks you create later can cite #step-3, and a reviewer's comments stay findable.
• Developers read it as text. Implementation tasks derived from this analysis get the report's text rendition in their run context (headings, paragraphs, lists, table rows, code blocks — markup dropped). Structure it so that rendition reads well: real headings, real lists, real tables.
• Open questions are not part of this document. A genuine product decision the code can't settle is recorded with record_open_questions (open-questions-protocol), never written here and never asked with ask_user. The system renders every open question as an answer box above this report automatically — the risks section below is risks only.

Required sections (in this order, with these ids)

1. summary — Summary. What is being built and why, in 3–6 sentences, then one callout decision stating the chosen approach. A reviewer who reads only this knows what they are approving.
2. context — Context & current state. What exists today, grounded in code you read: a table of real file paths and symbols (internal/application/task/service.go — TaskService.ListByProject) with what each does now. No path or symbol you did not see in this run.
3. design — Proposed design. Components with exact interfaces (names, parameter and return types), data flow, error handling, what the user sees, and the 2–3 approaches you weighed with the one-line reason the chosen one won. A decision worth remembering (new dependency, datastore/schema shape, API/contract pattern, auth/security architecture, cross-repo integration) gets a <h3 id="design-decision"> decision record (spec-authoring); skip it for a bug fix or config change. A Security & data subsection names who may call each new interface, which inputs are attacker-controlled, and what data leaves the system. Out-of-scope items are listed explicitly.
4. diagrams — Diagrams (only where they help: a request flow, a state machine, a component boundary). Inline <svg> with a <title> — its title is what the text rendition shows. Omit the section rather than draw a box that restates a sentence.
5. plan — Implementation plan. Numbered steps (<ol class="steps">, each <li id="step-N">): files to create/modify/test with exact paths, the interfaces each step consumes and produces, and the TDD cycle with the actual test code and the command to run. No placeholders — "add error handling", "similar to step 2" and "TBD" are plan failures (implementation-plan-authoring).
6. split — Task split. One row per project/repository: the repository, the layer, the one-line scope of its implementation task, the plan steps it owns, and its order (blocked_by / deploy_depends_on). This is what the human is approving you to create.
7. risks — Risks. Each risk with its mitigation. Open questions do not go here (or anywhere in the HTML) — record them with record_open_questions instead (open-questions-protocol); the system renders them above the report as answer boxes.