Review Work

Verify that a node in testing actually satisfies its contract, route it accordingly, and leave the documentation complete. Prerequisite: flownix-basics.

0. Load project context

cat .flownix 2>/dev/null || cat .ai-flow

Parse the YAML for project_id. Neither file exists → run flownix-init.

1. Load the full picture

• get_node on the task: the acceptance criteria in content, the executor's [progress]/[done] comments, tags, and its component links.
• If the criteria lean on parent context, get_node the parent plan/feature too.
• Surface the decisions and docs the change must stay consistent with:

  rag_query({ project_id, query: "<subsystem> architecture decision", kind_filter: "doc" })
  rag_query({ project_id, query: "<what the task changed>", k: 5 })

  A change contradicting a recorded [decision] is a review finding, not a detail. Confirm every hit with get_node before citing it. See flownix-rag-search.

2. Verify against criteria, not vibes

Walk each acceptance criterion explicitly and confirm it is met: correctness against the stated criteria, the edge cases and error handling the spec names, and whether the executor's [done] summary matches what is actually there. Verify, don't trust.

Check the component binding as part of the review: does the node point at the parts of the system the diff actually touched? A change to another service that left the link behind is a finding — fix it with set_node_components (it replaces the set, so pass the full list), or create_component if the part it touched has no component yet.

3. Record the review as memory

add_comment with [review]: a checklist with PASS/FAIL per criterion, and concrete, actionable notes for every failure — file, line, behaviour, not "looks off".

4. Route the node

• Passes → update_node_status done, plus a short [done] confirmation.
• Needs fixes → regression (or in_progress if it was never verified once) with a [review] comment listing exactly what must change. Lower update_node_progress if useful.
• Blocked externally → blocked with a [blocker] comment.

5. Document the feature (after task → done)

When a task passes and all tasks under its plan are done, write the feature's documentation:

create_doc_node({ project_id, parent_slug: "<FEAT slug>", title: "…", content: "…",
                  components: ["AF-COMP-3"] })
set_references({ slug: "<FEAT slug>", ref_slugs: ["<DOC slug>"] })
add_tag({ slug: "<DOC slug>", tag: "docs" })

• The doc is bound to components too — same rule as any node, and several are normal. No matching component → create_component first. An unbound spec is unreachable from the service it describes.
• The doc is not delivered until the feature references it. Both calls or neither.

Doc template: Overview (what it delivers) · Architecture (how it fits, key components and interactions) · API changes (new/modified endpoints, RPCs) · Usage examples · Implementation notes (decisions, trade-offs, known limits) · References (KEY-KIND-N — Title).

6. Cascade

1. All tasks under a plan done → plan done.
2. All plans under a feature done → doc + references written → feature done.
3. All features under an epic done → epic done, with a [done] comment naming them.

Rules

• A review without explicit per-criterion verdicts is not a review.
• Never pass a criterion you could not actually confirm — say so instead.
• Leave the ticket so the executor knows precisely what to do next without asking you.
• Never close a feature without its doc, its set_references link, and its component binding.
• Doc nodes are the highest-value entries in the semantic index — write explicit subject names and searchable domain terms, not "the service" / "the endpoint".