Forensic Review

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 via MCP:

sam_task(plan="{plan_id}", task="{task_id}", config={"action": "read"})

{plan_id} and {task_id} are the address already supplied to the call above — retain them as-is for the rest of this workflow; sam_task(action="read") returns a TaskAssignment with no top-level plan_id/task_id fields (the plan is plan-number, the task is nested at task.id), so do not attempt to re-extract the address from the response. Never parse plan_id for a plan number or slug — read those from sam_plan(config={"action": "read"}).

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_plan(plan="{plan_id}", config={"action": "read"})

Take the response'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_task(
  plan="{plan_id}",
  task="{task_id}",
  config={"action": "update", "append_section": "Review Results", "section_content": "{artifact_content}"}
)

Input

• ARTIFACT:EXECUTION + ARTIFACT:TASK via sam_task(plan="{plan_id}", task="{task_id}", config={"action": "read"})
• 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 SAM task via sam_task(action='update')
• Blocking findings (if any) have concrete remediation tasks created