forensic-review

Load dh:dh-cli-usage before using <sam_cli/> or <dh_scripts/>.

SAM Stage 6 — Forensic Review

Role

SAM Stage 6 delegates the concrete review work to @dh:code-reviewer. This skill is the orchestration wrapper: it resolves the task context, dispatches the agent, and maps its structured output back to the SAM pipeline verdict.

Producer and reviewer must always be different agents — never invoke this skill from the same agent that executed the task.

Core Principle

AI cannot reliably self-evaluate. The agent that wrote the code cannot objectively assess its own work. Forensic review uses a separate agent with fresh context to verify claims against observable evidence.

When to Use

• After Stage 5 Execution produces ARTIFACT:EXECUTION
• For each completed task before marking it as done
• When re-reviewing after a NEEDS_WORK remediation cycle

Process

flowchart TD
    Start([ARTIFACT:EXECUTION + ARTIFACT:PLAN]) --> R1[1. Resolve task context]
    R1 --> R2[2. Dispatch @dh:code-reviewer]
    R2 --> R3[3. Consume verdict from STATUS output]
    R3 --> R4[4. Read code-review artifact]
    R4 --> Decide{Verdict?}
    Decide -->|PASS| Complete[Verdict — COMPLETE]
    Decide -->|NEEDS-WORK or FAIL| NeedsWork[Verdict — NEEDS_WORK]
    Complete --> Done([ARTIFACT:REVIEW registered by agent])
    NeedsWork --> Remediate[Create remediation tasks from blocking findings]
    Remediate --> Done

Step 1 — Resolve Task Context

Read the task and everything its attempts recorded:

<sam_cli/> plan read --address {plan_id}/{task_id}

Read without --attempt: you are reviewing this task, not working an attempt on it, and naming an attempt you do not hold is refused as stale-attempt.

The result carries the task row and the sections every attempt appended — the Completion Report and Verification Results the runner wrote are what this review is against.

{plan_id} and {task_id} are the address already supplied to the call above — retain them as-is for the rest of this workflow, and never parse {plan_id} for a plan number or slug. Read the slug from the plan row instead.

From the response, extract:

• item_id — required for artifact registration; if absent, BLOCK immediately
• expected_outputs — the implementation files produced by Stage 5 (listed in the task's "Files Changed" or "Expected Outputs" section)
• acceptance_criteria — the explicit success conditions to verify

Step 2 — Dispatch @dh:code-reviewer

Delegate the concrete S6 review work with subagent_type="dh:code-reviewer".

Context to include in the prompt:

• plan_id and task_id — the SAM task address
• implementation_files — the files from the task's Expected Outputs
• item_id — required for artifact_register inside the agent

Task is S6 forensic review with subagent_type="dh:code-reviewer"
Context: plan_id={plan_id}, task_id={task_id}, item_id={item_id},
  implementation_files={expected_outputs}
Output: STATUS block containing Verdict (PASS / FAIL / NEEDS-WORK) and ARTIFACTS
  section naming the code-review artifact_id registered on issue #{item_id}

The agent independently reads the task, detects the stack, verifies acceptance criteria, applies universal and stack-specific quality dimensions, and registers the review report as a code-review artifact via artifact_register.

Step 3 — Consume Verdict

Parse the agent's STATUS output:

• Verdict: PASS → map to SAM verdict COMPLETE
• Verdict: NEEDS-WORK or Verdict: FAIL → map to SAM verdict NEEDS_WORK

If the agent returns STATUS: BLOCKED, propagate the block upstream with the agent's NEEDED section as the reason.

Step 4 — Read code-review Artifact

Take {artifact_id} from the ARTIFACTS section of the agent's STATUS output in Step 3 and retrieve that entry:

artifact_read(item_id={item_id}, artifact_type="code-review", artifact_id="{artifact_id}")

Address the entry by its artifact_id. One code-review entry exists per reviewed task, so when two tasks of this work item have been reviewed, omitting artifact_id returns whichever review registered last — which may be another task's.

If the STATUS output named no artifact_id, derive it. code-reviewer builds code-review-{task_id}-{plan_slug} from the plan it was dispatched under. Read that plan's slug from SAM — {plan_id} is an opaque logical identifier such as Pdec8934d and has no slug to parse out of it:

<sam_cli/> plan status --plan-address {plan_id}

Take the plan row's feature field as {plan_slug}, making the expected identifier code-review-{task_id}-{plan_slug}. Confirm it exists:

artifact_list(item_id={item_id}, artifact_type="code-review")

Match artifact_id exactly. Never select by substring and never fall back to the latest created_at: this work item also holds the quality gate's code-review-T1-qg-{plan_slug} verdict and the verdicts of every other task reviewed against it, and several of those contain this task's {task_id} as a substring. A loose match returns another task's review, which Step 5 would then append to this task's Review Results and mine for remediation findings that belong elsewhere.

If no entry matches exactly, stop and report BLOCKED naming the identifier that was expected and the identifiers artifact_list returned. Step 2 dispatched the reviewer moments earlier, so a missing verdict is a failure to report, not a condition to work around.

Use this to populate the SAM task's Review Results section and to extract blocking findings for remediation task creation.

Append review results to the task:

<sam_cli/> plan update \
  --plan-address {plan_id} --task-id {task_id} \
  --append-section "Review Results" --section-content "{artifact_content}"

No --attempt here either. A section named Completion Report or Verification Results is the runner's and requires the attempt that wrote it; every other section, this one included, is appended by whoever has something to record and is tagged with the task's current attempt count.

Input

• ARTIFACT:EXECUTION + ARTIFACT:TASK via plan read --address {plan_id}/{task_id}
• item_id — must be present; used by @dh:code-reviewer for artifact_register and by this skill for artifact_read
• artifact_id — returned by @dh:code-reviewer in its STATUS ARTIFACTS section; addresses the verdict for this task specifically

NEEDS_WORK Remediation Loop

When the verdict is NEEDS_WORK or FAIL, extract blocking findings from the code-review artifact's "Required changes (blocking)" or "Blocking" section.

flowchart TD
    NW([NEEDS_WORK verdict]) --> Extract[Extract blocking findings from code-review artifact]
    Extract --> Create[Create remediation tasks — one per blocking finding]
    Create --> Stage5[Stage 5 — Execute remediation tasks]
    Stage5 --> Stage6[Stage 6 — Re-review via @dh:code-reviewer]
    Stage6 --> Q{PASS?}
    Q -->|Yes| Done([Proceed to next task or Stage 7])
    Q -->|No| Extract

Remediation tasks follow the same CLEAR format as original tasks. They:

• Reference the specific blocking finding (file:line from the code-review artifact)
• Define acceptance criteria that directly resolve the blocking finding

Behavioral Rules

• Verdict is sourced from @dh:code-reviewer STATUS output — do not invent it
• Blocking findings for remediation come from the code-review artifact — do not invent them from the agent's STATUS summary
• Do not add new requirements — review against the ORIGINAL acceptance criteria only
• Verification Gap findings are always BLOCKING (see @dh:code-reviewer agent for the full classification rule)

Success Criteria

• @dh:code-reviewer returns STATUS: DONE with a PASS, FAIL, or NEEDS-WORK verdict
• code-review artifact is registered on issue #{item_id} and its artifact_id is named in the agent's STATUS output
• Review Results appended to the task via plan update --append-section "Review Results"
• Blocking findings (if any) have concrete remediation tasks created