Improve Tree

Score the effectiveness of a tree using evidence from one of its sessions, find improvements in parallel, draft a plan in plans/, then commit and push.

Version: 1.0.0

Files

• improve-tree/TREE.yaml — main

Install

mkdir -p .abtree/trees/improve-tree \
  && curl -fsSL https://raw.githubusercontent.com/flying-dice/abtree/main/.abtree/trees/improve-tree/TREE.yaml \
         -o .abtree/trees/improve-tree/TREE.yaml

Run with Claude

claude "Using abtree CLI. Execute the 'improve-tree' workflow"

---

Diagram

---
title: "improve-tree"
---
flowchart TD
    Improve_Tree_Workflow{{"Improve Tree Workflow\n[sequence]"}}
    0_Identify_Target["Identify Target\n[action]"]
    Improve_Tree_Workflow --> 0_Identify_Target
    0_Score_And_Find{{"Score And Find\n[parallel]"}}
    Improve_Tree_Workflow --> 0_Score_And_Find
    0_1_Score_Effectiveness["Score Effectiveness\n[action]"]
    0_Score_And_Find --> 0_1_Score_Effectiveness
    0_1_Find_Improvements["Find Improvements\n[action]"]
    0_Score_And_Find --> 0_1_Find_Improvements
    0_Draft_Plan["Draft Plan\n[action]"]
    Improve_Tree_Workflow --> 0_Draft_Plan
    0_Commit_And_Push["Commit And Push\n[action]"]
    Improve_Tree_Workflow --> 0_Commit_And_Push

Tree definition

name: improve-tree
version: 1.0.0
description: Score the effectiveness of a tree using evidence from one of its sessions, find improvements in parallel, draft a plan in plans/, then commit and push.

state:
  local:
    session_ref: null         # execution id to analyse; null = pick the most recent non-current execution.
    tree_slug: null           # derived from the session.
    session_evidence: null    # what the agent extracted from the session.
    effectiveness_score: null # { score: 0..1, observations: [...] }
    improvements: null        # list of { kind, target, change, rationale }
    plan_path: null
    commit_sha: null
  global:
    authoring_guide: "run `abtree docs author` for the YAML authoring guide and the rules a tree should satisfy"

tree:
  type: sequence
  name: Improve_Tree_Workflow
  children:
    - type: action
      name: Identify_Target
      steps:
        - instruct: >
            If $LOCAL.session_ref is set, use it. Otherwise pick the most recent
            non-current execution from `abtree execution list` and write its id to
            $LOCAL.session_ref. Read `.abtree/executions/<id>.json` to derive the
            tree slug — store at $LOCAL.tree_slug. Extract evidence from the
            execution: how far it got, which nodes failed, retry counts, $LOCAL
            keys that ended up null vs populated, any stage_halt or failure
            statuses. Also read the tree YAML at `.abtree/trees/<tree_slug>/TREE.yaml`.
            Store the evidence (a structured object summarising the run) at
            $LOCAL.session_evidence.
        - evaluate: $LOCAL.tree_slug is set and $LOCAL.session_evidence is set

    - type: parallel
      name: Score_And_Find
      children:
        - type: action
          name: Score_Effectiveness
          steps:
            - evaluate: $LOCAL.session_evidence is set
            - instruct: >
                Score how effectively the tree drove the session. Consider: did
                the tree reach `done`, were any retries exhausted, were instructions
                clear enough that the agent never had to ad-lib, did evaluate
                gates fire on the values they should, were any $LOCAL keys
                set-but-unused or used-but-unset, did parallel composites order
                their children sensibly. Score in [0, 1] (1 = the tree drove the
                session cleanly with no friction). Per observation include:
                node_path, severity (low/med/high), evidence (one line pointing
                at what in $LOCAL.session_evidence justifies it). Store at
                $LOCAL.effectiveness_score = { score, observations }.

        - type: action
          name: Find_Improvements
          steps:
            - evaluate: $LOCAL.session_evidence is set
            - instruct: >
                Read $GLOBAL.authoring_guide for the tree authoring conventions.
                Propose concrete improvements to the tree at
                `.abtree/trees/$LOCAL.tree_slug/TREE.yaml`. Each improvement is
                an object: { kind: rename|reword|split|merge|add-evaluate|add-retries|other,
                target: node_name or yaml path, change: short description of
                the edit, rationale: what session_evidence motivates it }.
                Don't propose work the codebase already does well. Store the
                list at $LOCAL.improvements.

    - type: action
      name: Draft_Plan
      steps:
        - evaluate: $LOCAL.effectiveness_score is set and $LOCAL.improvements is set
        - instruct: >
            Write a draft plan to plans/<YYYY-MM-DD>-improve-<tree_slug>.md.
            Frontmatter: id, title, status: draft, author (from git config user.name),
            created (today), reviewed_by (empty). Body sections:
              ## Summary — one paragraph naming the tree, the session id, and
              the headline score.
              ## Effectiveness score — the score and the observations (each
              with node_path, severity, evidence).
              ## Improvements — the proposal list with kind/target/change/rationale.
              ## Open questions — anything that needs codeowner input before
              the changes are applied.
            Store the relative path at $LOCAL.plan_path.
        - evaluate: $LOCAL.plan_path is set

    - type: action
      name: Commit_And_Push
      steps:
        - evaluate: $LOCAL.plan_path is set
        - instruct: >
            Stage $LOCAL.plan_path, create a single commit with message
            "docs(plans): improve-tree review of <tree_slug> (session <session_ref>)",
            then push to the current branch's upstream. Capture the new HEAD
            SHA into $LOCAL.commit_sha. If the working tree had unrelated
            modifications, stage only $LOCAL.plan_path — do not bundle them.
            If push fails (no upstream, network, etc.), submit failure with
            the error message rather than retrying.