Resolve pipeline

The resolve pipeline takes a GitHub issue and turns it into a pull request. It's the most complex pipeline in Developer -- 13 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 --> H[docs_review]
    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 route 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.

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.

implementation

A standalone stage used when resolving GitHub sub-issues (issues with sub_issue_metadata). The agent makes code changes in a git worktree with full read/write access. After it finishes, Python captures the diff. If the diff is empty, the pipeline routes to infeasible_comment.

evaluation

A fresh session that reviews the diff from the implementation stage. The agent decides:

• pass -- changes look correct, move on
• needs_context -- something is missing or unclear

If the agent says needs_context, it drafts a comment explaining what's missing and the pipeline stops. No half-baked PR.

docs_review

Resumes the implementation 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:

1. Per implementation step -- each decomposed step gets its own commit (e.g. "Step 1/3: Add parser module")
2. Documentation updates -- committed separately after docs_review
3. 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
implementation	new	Clean slate for code changes (sub-issue path only)
infeasible_comment	resume:implementation	Knows what it tried
evaluation	new	Independent review of the diff
eval_comment	resume:evaluation	Needs the evaluation reasoning
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