--- name: analiz-html-report category: architecture description: Use when you write or revise the analiz deliverable - the ONE self-contained HTML report (spec and plan as sections) a human reviews passage by passage --- # 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: `. 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 `

` 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 `` with a `` — 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 (`
    `, each `
  1. `): 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. ## HTML rules - One complete document: ``, ``, `` with `` and an inline `

    CSV export of a project's tasks

    analiz · A-12 · 2026-09-26 · repositories: backend-api, web

    Summary

    Project owners need their tasks in a spreadsheet. …

    Decision: build the CSV in an application service and stream it from a new endpoint; the web board gets a download button.

    Context & current state

    WhereWhat it does today
    internal/application/task/service.go — TaskService.ListByProjectReturns a project's tasks, newest first; used by the board page.

    Proposed design

    Components

    TaskExporter.Export(ctx, projectID uuid.UUID) ([]byte, error) — …

    Alternatives considered

    ApproachWhy not
    Stream from the handlerUntestable without HTTP.

    Decision record

    Problem: need a reusable, testable export path. Drivers: testability without HTTP, reuse by a future scheduled export. Chosen: an application service returning bytes, because it is unit-testable and the handler stays thin. Consequences: Good, because tests don't need an HTTP harness. Bad, because large exports hold the full CSV in memory (mitigated in risks).

    Security & data

    Only the project's owner may call the export endpoint (reuses the existing project-scoped auth middleware); no new data leaves the system beyond what the user already sees in the board.

    Out of scope: PDF, scheduled export, column selection.

    Diagrams

    Export request flow GET /export TaskExporter TaskRepository
    The handler validates the id; the exporter owns the CSV shape.

    Implementation plan

    1. TaskExporter service backend-api

      Files: create internal/application/export/service.go; test internal/application/export/service_test.go

      Consumes: TaskRepository.ListByProject(ctx, id) ([]Task, error) · Produces: Export(ctx, projectID uuid.UUID) ([]byte, error)

      Failing test first:

      func (s *ExportSuite) TestExport_encodesHeaderAndRows() { … }

      Run: go test ./internal/application/export/... -run TestExport → FAIL, implement, → PASS.

    Task split

    RepositoryLayerTaskStepsOrder
    backend-apibackendExport endpoint and service1–2first

    Risks

    Risk: large projects — mitigation: stream rows, cap at 50k.
    ``` ## Revising the report The report is revised in place, never replaced. After a review (the task comes back from `need_revision`): 1. Read the comments — they are in your run context under "Review comments on your analysis document", and `list_document_annotations` (status `submitted`) returns them all with the quoted passage. 2. Read the report's source: `list_task_documents` with the analiz task, its `document_id` and `raw: true`; follow `next_offset` until you have all of it. 3. Fix every comment at its root — re-read the code where a comment questions a fact — with `update_task_document` on the same `document_id`: `edits` (each `old_text` copied exactly from the source, occurring once) for targeted changes, `content` for a rewrite. Keep the section and step ids, and keep the document's TITLE unchanged — a new date in the title creates a second document instead of revising this one, since `add_task_document`/`update_task_document` match by exact title. Do not touch `split` unless a comment or a code re-read gives you a reason to — the human already approved its shape once. 4. Answer every comment with `resolve_document_annotations`: one line per comment saying what changed and where (`"Switched to a cron job — see #design and #step-2"`), or why you deliberately kept it. ## Self-review (before the run ends) - All seven sections present with their ids; the `plan` steps are `step-1…step-N`. - **Grounding pass** — before attaching, re-verify every claim, not just that you made some exploration call earlier: every path in `context` and `plan` exists (`get_repo_tree`/`grep_code`) or the step says *create*; every consumed symbol's signature matches what `get_symbol_skeleton` shows now; every third-party call matches the version locked in the lockfile; every verify command appears in `list_component_checks` or `get_project_brief`. Anything you cannot verify this way is removed from the plan; if it's a risk worth flagging, note it in `risks`; if only the human can decide it, record it with `record_open_questions` (open-questions-protocol) — never left in as an assumption. - No `