Resolve pipeline¶

The resolve pipeline takes a GitHub issue and turns it into a pull request. It's the most complex pipeline in Developer -- 10 stages with branching logic based on what the agent finds.

developer resolve assistant 25
developer resolve https://github.com/gregology/assistant/issues/25

Flow¶

flowchart TD
    A[triage] --> B{decision?}
    B -->|ask / propose| C[comment_draft]
    B -->|action_proposed / action_direct| DC[decompose]
    B -->|decline / decision| R[record_decision]
    DC --> DC1([implement steps + commit each])
    DC1 --> DQ{anything committed?}
    DQ -->|yes| H[docs_review]
    DQ -->|no| X[infeasible_comment]
    X --> X1([post comment])
    X1 --> STOP7[STOP]
    C --> C1([post comment])
    C1 --> STOP1[STOP]
    R --> R1[craft_decision_pr]
    R1 --> R2([commit, push, open PR])
    R2 --> STOP6[STOP]
    H --> HC([commit docs changes])
    HC --> Q{quality tools pass?}
    Q -->|yes| I[craft_pr]
    Q -->|no, attempts < 3| J[quality_fix]
    Q -->|no, attempts = 3| K[craft_draft_pr]
    J --> JC([commit fixes])
    JC --> Q
    I --> I1([push, open PR])
    I1 --> STOP4[STOP]
    K --> K1([push, open draft PR])
    K1 --> STOP5[STOP]

Stages¶

triage¶

Reads the issue, explores the codebase, and picks a path. This is always the first stage. The agent returns a TriageResult with one of these decisions:

ask -- needs clarification from the issue author
propose -- wants to describe its approach before implementing
action_proposed -- ready to implement with a described approach
action_direct -- ready to implement immediately
decline -- the issue shouldn't be implemented (with reasoning)
decision -- this is an architectural decision, not a code change

Both action_proposed and action_direct lead to the decompose stage, which plans the implementation as one or more atomic steps.

decompose¶

Resumes the triage session and plans the implementation as 1–5 steps, each producing an independent commit. The agent produces a DecomposePlan identifying the steps. Then post_decompose_action implements each step sequentially in a fresh session and commits after each one. A single step is common for straightforward changes.

If no step commits anything, the pipeline routes to infeasible_comment instead of docs_review. That stage resumes the last step's session, or the decompose session if the plan had no steps, and explains on the issue why nothing changed. Python posts the comment.

comment_draft¶

Resumes the triage session and drafts a comment. Used for the ask and propose paths. Python posts the comment. Pipeline stops.

record_decision / craft_decision_pr¶

For declined issues and architectural decisions. The agent updates the project's decision log, then crafts a PR documenting why it's not implementing the change. Even declines get tracked as PRs so there's a reviewable record.

docs_review¶

Resumes the last implementation step's session. The agent checks whether docs need updating given the changes. After it finishes, Python commits any documentation changes, then runs the repo's configured quality tools.

quality_fix¶

If quality tools fail, the agent gets the tool output and tries to fix the issues. After each attempt, Python commits the fixes and re-runs quality tools. This can loop up to three times. If quality tools still fail after three attempts, the pipeline moves to craft_draft_pr instead.

craft_pr / craft_draft_pr¶

The final stage. The agent crafts a branch name, commit message, and PR body. Python pushes the branch and opens the PR.

craft_draft_pr is the fallback when quality tools won't pass. It opens a draft PR and notes the remaining issues so a human can finish up.

Commit strategy¶

The pipeline creates atomic commits at each meaningful boundary:

Per implementation step -- each decomposed step gets its own commit (e.g. "Step 1/3: Add parser module")
Documentation updates -- committed separately after docs_review
Quality fixes -- committed separately after each quality_fix pass

All commits are squashed when the PR is merged, so the individual commits exist purely to make review easier. A reviewer can use commit-by-commit review to examine each concern independently.

Session strategies¶

Stage	Session	Why
triage	`new`	Fresh start, no assumptions
decompose	`resume:triage`	Needs the triage context to plan steps
comment_draft	`resume:triage`	Needs the triage context to write a good comment
record_decision	`resume:triage`	Needs the decline reasoning
craft_decision_pr	`resume:record_decision`	Needs both the decision and the triage context
docs_review	`resume:implementation`	Knows the codebase from implementing
quality_fix	`resume:implementation`	Needs the implementation context to fix issues
craft_pr	`resume:implementation`	Knows what changed and why
craft_draft_pr	`resume:implementation`	Same as craft_pr
infeasible_comment	`resume:implementation`	Knows what the steps tried

Each implementation step runs as implement_step_<n> in a new session. resume:implementation resumes the last step's session.

Dry run¶

With --dry-run, the whole pipeline runs, implementation steps included, in the run's own worktree. Nothing is pushed and nothing is posted. Developer prints the PR or comment it would have created, followed by the full diff of the run's changes.