Refine Plan

Refine a one-line change request into a hardened, codeowner-reviewable plan: analyse intent, draft a structured plan, critique as a Staff Engineer, save to plans/.

Version: 3.0.0

Files

• refine-plan/TREE.yaml — main

Install

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

Run with Claude

claude "Run the abtree refine-plan tree. Use 'abtree --help' to learn the execution protocol, then create an execution with 'abtree execution create refine-plan \"<summary>\"' and drive it to completion."

---

Tree definition

name: refine-plan
version: 3.0.0
description: "Refine a one-line change request into a hardened, codeowner-reviewable plan: analyse intent, draft a structured plan, critique as a Staff Engineer, save to plans/."

state:
  local:
    change_request: null
    intent_analysis: null
    draft_plan: null
    hardened_plan: null
    plan_path: null

tree:
  type: sequence
  name: Refine_Plan_Workflow
  children:
    - type: action
      name: Understand_Intent
      steps:
        - evaluate: $LOCAL.change_request is set
        - instruct: >
            Analyze $LOCAL.change_request. Determine:
            - What is being asked for? (feature, fix, refactor, migration, etc.)
            - What systems/files are likely affected?
            - What are the constraints and requirements?
            - Who are the likely codeowners? (check CODEOWNERS file if present)
            - What acceptance criteria would prove this is done?
            Store your analysis at $LOCAL.intent_analysis.

    - type: action
      name: Write_Draft
      steps:
        - evaluate: $LOCAL.intent_analysis is set
        - instruct: >
            Based on $LOCAL.intent_analysis, draft a change spec with this structure:


            ---

            id: [generate using format: {timestamp}-{adjective}-{noun}-{verb}]

            title: [concise title]

            status: draft

            author: [from git config user.name]

            created: [today's date]

            reviewed_by:

            ---


            ## Summary

            [1-3 sentences on what this change does and why]


            ## Requirements

            [Bulleted list of functional requirements]


            ## Technical Approach

            [How this will be implemented — files, patterns, dependencies]


            ## Affected Systems

            [List of systems/modules/services touched]


            ## Acceptance Criteria

            [Testable conditions that prove the change is complete]


            ## Risks & Considerations

            [Edge cases, backwards compatibility, performance, security]


            ## Open Questions

            [Anything unresolved that needs codeowner input]


            The reviewed_by field MUST remain empty. Only a codeowner can add their name there.
            Store the draft at $LOCAL.draft_plan.

    - type: action
      name: Critique_Draft
      steps:
        - evaluate: $LOCAL.draft_plan is set
        - instruct: >
            Act as a Staff Engineer reviewing a change plan. Evaluate $LOCAL.draft_plan:

            - Is the scope clearly bounded? (no creep, no ambiguity)
            - Are requirements specific enough to implement without guessing?
            - Does the technical approach account for existing patterns in the codebase?
            - Are acceptance criteria testable and complete?
            - Are risks realistic (not hypothetical paranoia)?
            - Are open questions genuine blockers or just hedging?

            Tighten, clarify, and remove anything vague. Output a hardened plan.
            Store the result at $LOCAL.hardened_plan.

    - type: action
      name: Save_Plan
      steps:
        - evaluate: $LOCAL.hardened_plan is set
        - instruct: >
            Write $LOCAL.hardened_plan to the plans/ folder.
            Filename: plans/[kebab-case-title].md
            Derive the filename from the plan title.
            Create the plans/ directory if it does not exist.
            Store the file path at $LOCAL.plan_path.