analiz-human-review-gate
Use when you finish an analiz report - the human must approve the analysis before any implementation task is created, via the analiz_review column
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 122
- Forks
- 18
01 前言 Front Matter
- name
- analiz-human-review-gate
- source
- obra/superpowers (MIT), adapted
- category
- architecture
- description
- Use when you finish an analiz report - the human must approve the analysis before any implementation task is created, via the analiz_review column
03 SKILL.md 正文
Analiz Human Review Gate
Overview
Your analysis output — the ONE analysis report, with the spec and the implementation plan as its sections — is not self-approved. A human reviews it BEFORE any implementation task exists. This is the only human gate in the system: the human does not review individual dev tasks, but they DO review your plan, because a wrong plan multiplies into wrong tasks across every project.
The human reviews the report passage by passage: they select text in it, comment on it, and send all their comments back at once. Each comment is anchored to the words it is about, so it is precise — and every one of them needs an answer.
Core principle: No implementation task is created from an unapproved plan. You stop, the task waits at analiz_review, and you create nothing until the human approves.
This reverses the old flow. You no longer create tasks and then close the analiz. You present the plan, wait for approval, and only THEN create tasks.
The Gate
digraph gate {
"Report written\n& self-reviewed" [shape=box];
"Summary comment, STOP\n(system moves -> analiz_review)" [shape=box];
"Human decision" [shape=diamond];
"Human moves -> done\n(approved)" [shape=box];
"Human sends comments\n-> need_revision (rejected)" [shape=box];
"Create per-project impl tasks\n+ list them" [shape=box];
"Move analiz -> released" [shape=doublecircle];
"Fix every comment at root\nin the SAME report, resolve each\n(system moves -> analiz_review)" [shape=box];
"Report written\n& self-reviewed" -> "Summary comment, STOP\n(system moves -> analiz_review)";
"Summary comment, STOP\n(system moves -> analiz_review)" -> "Human decision";
"Human decision" -> "Human moves -> done\n(approved)" [label="approve"];
"Human decision" -> "Human sends comments\n-> need_revision (rejected)" [label="request changes"];
"Human moves -> done\n(approved)" -> "Create per-project impl tasks\n+ list them";
"Create per-project impl tasks\n+ list them" -> "Move analiz -> released";
"Human sends comments\n-> need_revision (rejected)" -> "Fix every comment at root\nin the SAME report, resolve each\n(system moves -> analiz_review)";
"Fix every comment at root\nin the SAME report, resolve each\n(system moves -> analiz_review)" -> "Human decision";
}
Step 1 — Present for review (do NOT create tasks yet)
When the report is written, self-reviewed, and attached via add_task_document (format: "html", analiz-html-report):
add_task_comment— a review-ready summary for the human:- One-paragraph approach (what will be built and why this approach).
- The title of the report you attached (
analiz: …). - The project/task split you INTEND to create on approval — list each project and the one-line scope of its task (see project-split-decomposition). This is what the human is approving.
- Any product decision you need confirmed.
- STOP. Your run ends here. When a run ends with the report attached, the system moves the analiz task to analiz_review for you — do not move it yourself. Create nothing. Do not touch implementation tasks.
Step 2 — Handle the human's decision
You are re-dispatched (as the analiz task's assignee) when the human decides. The task's current column tells you which path:
Column is done → APPROVED.
- Check for answered open questions first (
list_open_questionsif the context block doesn't already show them). An unanswered non-blocking question means itsrecommended_answerstands. If a human's answer contradicts the approved split or plan in a way this decomposition cannot absorb, do NOT decompose —add_task_commentnaming the conflict and stop (open-questions-protocol). - Now create the per-project implementation tasks (project-split-decomposition + task-decomposition).
- Every one of them carries
derived_from: ["<this analiz task's key>"]. Your report — spec and plan — is a document on THIS task and exists nowhere else — the reference is what puts it in front of the developer and what makeslist_task_documentsable to return it. A task without it is a task whose specification cannot be found. - Every ordering between them goes in
blocked_by(who codes first) anddeploy_depends_on(who ships first), not in the description. add_task_commentlisting every created task: title, assignee, project, and its order.move_board_taskthe analiz task to released. You are finished.
The run is a revision (the task came back through need_revision) → REJECTED.
- Read EVERY review comment. They are in your run context under "Review comments on your analysis document" — each with its id, the quoted passage and the human's comment. If that list says some were left out, or you are unsure you have them all,
list_document_annotationswith statussubmittedreturns every one. Also read the task comments: the review's covering note is there. - Read the report's source:
list_task_documentson this task with the report'sdocument_idandraw: true; follownext_offsetuntil you have all of it. - Fix each comment at the root of the concern (see root-cause-review reasoning — fix the cause, not the wording). Where a comment questions a fact about the code, re-read the code before you answer it.
- Honour every answered open question the same way (
list_open_questionsif you need the full list): fold the answer into the report and withdraw or replace any question it made moot. An unanswered non-blocking question means itsrecommended_answerstands — do not re-ask it (open-questions-protocol). - Revise the SAME report with
update_task_documenton itsdocument_id—edits(eachold_textcopied exactly from the source) for targeted passages,contentfor a rewrite. Keep its sections and ids, and keep its TITLE unchanged (a new date creates a second document instead of revising this one). Never attach a second document. Leavesplitas the human approved unless a comment or a code re-read gives you a concrete reason to change it. - Re-run the design and plan self-reviews on the revised report.
resolve_document_annotationsONCE, with{id, reply}for every comment you were sent: the reply is one line saying what changed and where ("Replaced the queue with a cron job — see #design and #step-2"), or why you deliberately kept it.add_task_commentwith a short summary of what changed. Then STOP: when the run ends with the report revised, the system moves the task back to analiz_review — do not move it yourself.- Create no implementation tasks. A rejected analysis never spawns work.
Common Mistakes
- Creating implementation tasks before approval — the whole point of the gate is that tasks come AFTER the human says yes.
- Moving the analiz task yourself to
analiz_review,doneorneed_revision— the system moves it toanaliz_review, anddone/need_revisionare the human's decisions. You move it only toreleased, after approval. - Answering some review comments and not others — every submitted comment gets a fix (or a reasoned "kept") and a reply.
- Resolving a comment without changing the report — the reply is a record of the fix, not a substitute for it.
- Attaching a revised report next to the old one — revise in place with
update_task_document. - On rejection, tweaking wording instead of addressing the concern — the human will reject again.
- Forgetting to list the intended project/task split in the review comment — the human is approving the split, so show it.
- Decomposing while a human's answer to an open question still contradicts the approved split — resolve the conflict with the human first (open-questions-protocol).
Red Flags — STOP
- You are about to call create_board_task and the analiz task is still in
analiz_review→ you are creating tasks before approval. - You created implementation tasks without
derived_from→ they point at no analysis, and the report you spent the run writing is unreachable from the work it specifies. - You are about to call
move_board_tasktoanaliz_reviewordone→ that is the system's move or the human's, not yours. - You are about to call
add_task_documentduring a revision → revise the existing report withupdate_task_documentinstead. - A revision came back and you are editing task titles instead of the report → you are patching symptoms.
04 同仓库更多 Skills
visual-craft
暂无简介
ux-copy
Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check
screen-mockup-html
Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task
performance-awareness
How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.
design-variants
Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision
design-system-authoring
Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns