review-retry-succeeds

Scenario for Technical Writer.

First review fails on atomicity; retry passes after narrowing scope

Latest run: PASS — 2026-05-10 23:28:14Z

Spec: .abtree/trees/technical-writer/TEST__review-retry-succeeds.yaml

Report: .abtree/trees/technical-writer/REPORT__review-retry-succeeds__20260510T232814Z.md

---

Test spec

feature: Technical_Writer grounds a docs goal in a styleguide, places it, writes, and review-gates
tree: technical-writer
description: |
  Retry path — first write fails the atomicity check; the runtime retries
  Write_And_Review and the second pass clears the gate. Tests the bounded
  retry behaviour of the Write_And_Review sequence (retries: 2 in the
  tree). After this run, runtime.retry_count.Write_And_Review should be 1.

background:
  initial:
    local:
      goal: "Document trace inspection — the .mermaid file format, how to read node colours, and how to debug a stuck execution from the trace alone."

fixtures:
  side_effects:
    styleguide_load:
      exists: true
      contents: "# Styleguide\n- Sentence case headings.\n- Code fences with language tag.\n"
    docs_home_lookup:
      home_exists: true
      placement: docs/guide/inspecting-executions.md
      adjacency:
        - docs/guide/getting-started.md
        - docs/guide/runtime-protocol.md
    docs_write:
      file_written: docs/guide/inspecting-executions.md
    review_outcomes:
      # First attempt fails atomicity — the writer bundled two concepts (mermaid format AND debugging) into one page.
      - attempt: 1
        verdict: failed
        notes: |
          Atomicity (3) — failed. The draft bundles two distinct concepts: the .mermaid file format,
          and debugging a stuck execution from a trace. Split: the file format belongs in this page;
          stuck-execution debugging belongs in a separate "Debugging executions" page.
      # Second attempt addresses the feedback: scope narrowed to the file format only.
      - attempt: 2
        verdict: approved
        notes: approved

scenario:
  name: First review fails on atomicity; retry passes after narrowing scope
  given:
    - $LOCAL.goal is set
    - STYLEGUIDE.md exists at the repo root
    - a docs home for the content exists
  when:
    - Resolve_Styleguide / Assess_Intent / Map_Placement run through to placement
    - Write_Documentation (attempt 1) writes a draft that bundles two concepts
    - Review_Gate (attempt 1) runs three checks; per fixtures.side_effects.review_outcomes[0] verdict is "failed"
    - Review_Gate (attempt 1) writes the atomicity-failure note to $LOCAL.review_notes
    - Review_Gate (attempt 1) evaluate → false ($LOCAL.review_notes is not "approved") → action fails
    - Write_And_Review parent sequence fails → runtime retries (retry_count: 0 → 1)
    - Write_Documentation (attempt 2) reads $LOCAL.review_notes as prior feedback, narrows scope to mermaid file format only
    - Review_Gate (attempt 2) verdict "approved" per fixtures.side_effects.review_outcomes[1]
    - Review_Gate (attempt 2) sets $LOCAL.review_notes = "approved", confirms final_path
  then:
    local:
      review_notes: approved
      final_path: equals fixtures.side_effects.docs_home_lookup.placement
    files:
      placement:
        exists: true
        path: equals fixtures.side_effects.docs_write.file_written
    runtime:
      retry_count:
        Write_And_Review: 1
    status: done

Latest report

Tree: technical-writer (v1.2.1) Runner: test-tree (v1.2.0, fixture-driven side effects) Spec: .abtree/trees/technical-writer/TEST__review-retry-succeeds.yaml Target execution: test-tree-run-trace-inspection-retry-pas__technical-writer__1 Overall: PASS

Final $LOCAL

key	value
goal	"Document trace inspection — the .mermaid file format, how to read node colours, and how to debug a stuck execution from the trace alone."
styleguide	"# Styleguide\n- Sentence case.\n"
intent	"type: reference + how-to; scope: one page; audience: integrator."
docs_survey
placement	"docs/guide/inspecting-executions.md"
draft	"# Inspecting executions (attempt 2: scope narrowed…)"
review_notes	"approved"
final_path	"docs/guide/inspecting-executions.md"

Assertions

Name	Expected	Actual	Pass
status	done	done	✓
local.review_notes	approved	approved	✓
local.final_path	equals fixtures.side_effects.docs_home_lookup.placement	docs/guide/inspecting-executions.md	✓
files.placement	exists at fixtures.side_effects.docs_write.file_written	(fixture) docs/guide/inspecting-executions.md	✓
runtime.retry_count.Write_And_Review	1	1 (runtime.retry_count["3"]=1)	✓

Retry verified: attempt 1's Review_Gate evaluated false on $LOCAL.review_notes is "approved" (verdict was the atomicity-failure note from fixture review_outcomes[0]); the runtime retried Write_And_Review; attempt 2 wrote a narrowed draft, Review_Gate approved per fixture review_outcomes[1], final_path was confirmed. retry_count.Write_And_Review = 1 as expected (one retry consumed out of the budget of 2).

Trace

---
title: "test-tree run: trace inspection — retry passes after narrowing scope (complete)"
---
flowchart TD
    Technical_Writer_Workflow{{"Technical Writer Workflow\n[sequence]"}}
    0_Resolve_Styleguide{{"Resolve Styleguide\n[selector]"}}
    Technical_Writer_Workflow --> 0_Resolve_Styleguide
    style 0_Resolve_Styleguide fill:#4ade80,stroke:#16a34a,color:#052e16
    0_0_Load_Styleguide["Load Styleguide\n[action]"]
    0_Resolve_Styleguide --> 0_0_Load_Styleguide
    style 0_0_Load_Styleguide fill:#4ade80,stroke:#16a34a,color:#052e16
    0_0_Bootstrap_Styleguide{{"Bootstrap Styleguide\n[sequence]"}}
    0_Resolve_Styleguide --> 0_0_Bootstrap_Styleguide
    0_0_1_Draft_Styleguide["Draft Styleguide\n[action]"]
    0_0_Bootstrap_Styleguide --> 0_0_1_Draft_Styleguide
    0_0_1_Human_Approval_Gate["Human Approval Gate\n[action]"]
    0_0_Bootstrap_Styleguide --> 0_0_1_Human_Approval_Gate
    0_Assess_Intent["Assess Intent\n[action]"]
    Technical_Writer_Workflow --> 0_Assess_Intent
    style 0_Assess_Intent fill:#4ade80,stroke:#16a34a,color:#052e16
    0_Survey_Existing_Docs{{"Survey Existing Docs\n[selector]"}}
    Technical_Writer_Workflow --> 0_Survey_Existing_Docs
    style 0_Survey_Existing_Docs fill:#4ade80,stroke:#16a34a,color:#052e16
    0_2_Map_Placement["Map Placement\n[action]"]
    0_Survey_Existing_Docs --> 0_2_Map_Placement
    style 0_2_Map_Placement fill:#4ade80,stroke:#16a34a,color:#052e16
    0_2_Resolve_Structure["Resolve Structure\n[action]"]
    0_Survey_Existing_Docs --> 0_2_Resolve_Structure
    0_Write_And_Review{{"Write And Review\n[sequence]"}}
    Technical_Writer_Workflow --> 0_Write_And_Review
    style 0_Write_And_Review fill:#4ade80,stroke:#16a34a,color:#052e16
    0_3_Write_Documentation["Write Documentation\n[action]"]
    0_Write_And_Review --> 0_3_Write_Documentation
    style 0_3_Write_Documentation fill:#4ade80,stroke:#16a34a,color:#052e16
    0_3_Review_Gate["Review Gate\n[action]"]
    0_Write_And_Review --> 0_3_Review_Gate
    style 0_3_Review_Gate fill:#4ade80,stroke:#16a34a,color:#052e16

Note: the live mermaid trace shows only the final-attempt node state. The retry history (attempt 1 red → attempt 2 green) lives in the runtime document at .abtree/executions/<id>.json under runtime.retry_count.