Skip to content

issue-refiner

Generates and refines implementation plans for issues, turning cold requirements into warm, actionable blueprints.

Property Value
Type Interval
Default interval 5 minutes (intervals.issueRefinerMs)
Uses AI Yes
Backend Claude (configurable via jobAi)
Config key intervals.issueRefinerMs

What it does

The issue-refiner is the planning engine at the heart of Yeti's workflow. It reads GitHub issues and produces detailed implementation plans -- which files to change, what the changes should be, risks, edge cases, and a suggested implementation order.

When feedback arrives on an existing plan, the refiner updates the plan in-place rather than posting a new comment, keeping the issue thread clean. It also handles follow-up questions on issues that already have open PRs.

Trigger

The refiner processes an issue when any of these conditions are met:

  1. New plan needed: Issue has the Needs Refinement label and no existing plan comment
  2. Re-plan requested: Issue has the Needs Refinement label and an existing plan (produces a fresh plan)
  3. Feedback to address: Issue has an existing plan with unreacted human comments posted after it
  4. Auto-plan exemptions: [ci-unrelated] or [yeti-error] issues (with triage report) are processed without requiring the Needs Refinement label
  5. Follow-up questions: Issues with open PRs and unreacted human comments after the plan

Labels

Label Action
Needs Refinement Requires (for new plans on regular issues)
Needs Refinement Removes (after posting plan)
Needs Plan Review Sets (if plan-reviewer is enabled and plan is actionable)
Ready Sets (if plan-reviewer is disabled and plan is actionable)
Ready Removes (when new feedback arrives)
Refined Sets (auto-refines [ci-unrelated] issues)

How it works

New Plan

  1. Creates an isolated git worktree for the repository
  2. Reads the issue body, all comments, and any referenced images
  3. Instructs Claude to read yeti/OVERVIEW.md and linked docs for codebase context
  4. Claude reads the relevant source files identified from the issue before planning (plans are grounded in actual code, not assumptions)
  5. Step 1 — Evaluate: Claude evaluates whether the issue provides enough detail for a confident plan. If underspecified, it outputs clarifying questions classified by severity:
    • ### Clarifying Questions (blocking) — Must be answered before a reliable plan can be written. When blocking questions are present, no implementation plan is produced and no workflow labels are added. The issue waits for human response.
    • ### Clarifying Questions (non-blocking) — The plan is fully implementable but Claude wants to confirm an assumption or preference. The full plan is included alongside the questions, and review proceeds normally.
    • ### Clarifying Questions (no suffix) — Treated as blocking by default.
  6. Step 2 — Draft: Claude drafts an initial implementation plan (text only, no code changes) when there are no blocking clarifying questions. For each file, the plan specifies what changes are needed and why (tied back to the issue requirement), along with:
    • Implementation order with rationale (e.g., types before consumers)
    • Dependencies between changes
    • Risks and edge cases
    • Testing approach (unit/integration/manual, with specific test file names)
  7. Step 3 — Self-critique: Claude performs two rounds of structured self-critique against four dimensions: unverified assumptions (did it actually read the files it referenced?), scope discipline (is anything beyond what the issue requires?), ordering and dependencies (would a developer hit errors following the steps in order?), and risk honesty (are failure modes omitted to keep the plan tidy?). After each round, the plan is revised to address every weakness found.
  8. Step 4 — Final plan: Claude outputs only the final revised plan, without intermediate drafts or critique notes
  9. Claude chooses the narrowest reasonable interpretation of ambiguous issues and notes assumptions explicitly
  10. Posts an ## Implementation Plan comment on the issue
  11. Transitions labels: removes Needs Refinement. If the plan is actionable (no blocking clarifying questions), adds Needs Plan Review or Ready. If the plan contains blocking clarifying questions, no workflow label is added — the issue waits for human response.
  12. For [ci-unrelated] issues with actionable plans: also adds Refined to skip human approval

Review loop re-entry

When reviewLoop is enabled, plan-reviewer can re-add Needs Refinement to trigger another refinement cycle. The issue-refiner handles this the same way as human-initiated re-refinement — it reads prior comments (including the review) and updates the plan.

Refinement (Feedback Loop)

  1. Detects unreacted human comments after the most recent plan
  2. Feeds the existing plan and new feedback to Claude with instructions to:
    • Address each feedback item individually (never silently drop feedback; explain disagreements)
    • Preserve plan sections not affected by the feedback to avoid regressions
    • Stay within the original issue scope (out-of-scope suggestions go in a separate ### Out of Scope section)
    • Read every source file that the feedback references before revising plan sections
    • Output a ### Clarifying Questions section (blocking or non-blocking) if any feedback is ambiguous or contradictory, rather than guessing
    • Perform a verification step: check all feedback was addressed, no plan items were accidentally removed, and implementation order is still correct
    • Include a testing approach for verifying the changes
  3. Claude produces an updated plan
  4. Edits the existing plan comment in-place (does not create a new comment)
  5. If Claude includes a ### Note section, it is posted as a separate comment
  6. Reacts with thumbsup to each addressed feedback comment
  7. If the updated plan is actionable, re-adds Needs Plan Review or Ready. If the plan contains blocking clarifying questions, no workflow label is added.

When no specific feedback is provided (e.g., a re-plan via label), the refiner asks Claude to re-evaluate the plan for missing files, edge cases, implementation order, and testing sufficiency.

Follow-Up Response

When an issue has an open PR but new human comments appear:

  1. Detects unreacted comments on issues with open Yeti PRs
  2. Feeds the existing plan, PR number, and follow-up comments to Claude
  3. Claude responds to questions and clarifications (no new plan produced)
  4. Posts the response as a comment
  5. Reacts with thumbsup to each addressed comment

Multi-PR Plans

The refiner instructs Claude to prefer single PRs but supports multi-PR plans for genuinely large changes. Multi-PR plans use a structured format (### PR 1: ..., ### PR 2: ...) that the issue-worker parses for phased implementation.