Analiz Task Workflow

The system-architect normally owns analiz tasks. The human can grant a developer the analyst role for an area (Settings → Roles); when that happens, an analiz task is dispatched to you instead of the architect. Your prompt's step 1 already tells you how to tell the two cases apart: add_task_document in your tool list means you ARE the analyst for this task — follow this skill. Otherwise comment that it is misassigned and take no other action.

Which instructions apply

An analiz task is not a code task. The standing acceptance criteria (build, suite, unit test), TDD, and the code_review hand-off that the rest of your prompt and columns describe do not apply here — the deliverable is a document, not a diff. File edits are discarded: an analiz task never publishes a branch and commit_task_changes refuses it — a run that produced edits on this task type has done the wrong job on the wrong task, and those edits reach nobody.

Explore

Ground every claim in code you actually opened in this run: get_repo_tree, codebase_search, grep_code, get_symbol_skeleton, expand_symbol_context. Name the real files, symbols and interfaces you found. A document that describes a codebase you did not open is rejected.

Deliverable

ONE report, via add_task_document with format: "html", titled analiz: <YYYY-MM-DD> <topic>. Required sections, each with a stable id, in this order:

• summary — what is being built and why, in 3–6 sentences, plus one decision callout stating the chosen approach.
• context — current state, grounded in code you read: real file paths and symbols, with what each does today.
• design — proposed components with exact interfaces (names, parameter and return types), data flow, error handling, the 2–3 approaches you weighed with the one-line reason the chosen one won, and out-of-scope items named explicitly.
• plan — numbered implementation steps (step-1, step-2, …): files to create or modify, the interfaces each step consumes and produces, and the TDD cycle with the actual test code and the command that runs it. No placeholders — "add error handling", "similar to step 2" and "TBD" are plan failures.
• split — one row per repository/layer: the one-line scope of its implementation task, the plan steps it owns, and its order (blocked_by / deploy_depends_on).
• risks — each risk with its mitigation. Open questions never go here (or anywhere in the HTML) — see "Open questions" below.

This mirrors the system-architect's own analiz-html-report skill — follow its HTML rules (one self-contained document, no <script>, no external resources, light/dark via CSS variables, under ~150 KB) and its template.

Open questions

A genuine product decision the code cannot settle is recorded with record_open_questions — never written into the report as prose, and never asked with ask_user (you do not hold ask_user on an analiz task). The system renders every recorded question as an answer box above your report; the human answers there, not in chat.

Each question is blocking (the analysis cannot responsibly continue without the answer — the exception: two incompatible product behaviours with no basis to choose, an external contract you cannot see, a scope choice that changes which repositories are touched) or non-blocking (a reasonable default exists — the default: record it with recommended_answer and keep working). recommended_answer is required whenever blocking is false.

A blocking question does not end the run early — explore everything else first and attach the report as far as it got (add_task_document/update_task_document), then record_open_questions, a summary comment, and STOP: the run ends in blocked instead of analiz_review, report attached. Re-dispatched after an answer (resumed: "questions_answered", or new answers in your run context) — list_open_questions if you need the full picture — continue the SAME report with update_task_document, and withdraw or replace any question the answer made moot.

On a revision or in later runs: honour every answer, the same way you honour review comments. An unanswered non-blocking question means its recommended_answer stands — do not re-ask it.

Revision

When the task comes back through need_revision: read the review comments (they are in your run context under "Review comments on your analysis document"; list_document_annotations with status submitted returns every one) and the report's current source (list_task_documents with the document's id and raw: true, following next_offset until you have it all). 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) for targeted passages, content for a rewrite. Keep the section and step ids. Honour every answered open question the same way (see "Open questions" above). Never attach a second document — the card ends with ONE current report.

Criteria

Tick only the acceptance criteria your report actually answers.

Close

End the run with a summary comment: your approach, the report's title, and the project/task split you intend. Then STOP. When the run ends with the report attached and no pending blocking question, the system moves the task to analiz_review for you; a pending blocking question moves it to blocked instead. Never move it yourself, and never to done. Create no implementation tasks — the system-architect decomposes them after the human approves your report, the same way it does for its own analyses. No git push: nothing here is committed.

Red Flags

• Editing repository files on an analiz task — they are discarded; write the document instead.
• A second add_task_document on a revision — revise the existing one with update_task_document.
• Moving the task yourself, or moving it to done or code_review.
• Writing a question as prose in the report, a task comment, or with ask_user instead of record_open_questions — you do not hold ask_user on an analiz task.
• A non-blocking question with no recommended_answer — refused; decide what you're proceeding on.