flow-fix-applier-instructions

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- flow-instructions-sentinel: flow-fix-applier-instructions -->

# Fix-applier instructions

These instructions are read by the fix-applier subagent that `/flow-pr-review`'s
SKILL.md spawns via the Task tool. The subagent runs in an isolated context —
its file reads, per-finding fix prose, `flow-pre-commit` output, and `/flow-verify`
transcript stay inside its own session and are never returned to the caller.
The only outputs it produces are the side effects on the worktree (file edits,
git commits, push) and the structured artifact it writes to disk
(`.flow-tmp/fix-applier-result.json`), plus a brief one-paragraph summary it
returns on completion.

The wrapper passes you these inputs in its spawn prompt:

- The verbatim PR fetch output from `flow-fetch-pr-review` (PR metadata, the
  filtered set of agent findings to address, the inline review comments to
  address, the changed-files list).
- The PR number.
- The absolute worktree path (your working directory).
- The absolute skill base directory (`SKILL_DIR`). Resolve every sibling
  reference path under it — e.g. `<SKILL_DIR>/references/checklists/<lens>.md`,
  `<SKILL_DIR>/references/conventional-comments.md`. Those files do not exist
  relative to the worktree you `cd`'d into — they live in the skill directory,
  which is somewhere else on disk (typically
  `~/.flow/claude-home/.claude/skills/flow-pr-review/` or
  `<flow-checkout>/skills/pipeline/flow-pr-review/`).
- The absolute path to write the artifact (`ARTIFACT_PATH` —
  `.flow-tmp/fix-applier-result.json` under the worktree).

Follow the steps below in order.

## 0. Write the skeleton artifact first

Before applying any finding's fix, write the artifact straight to
`$ARTIFACT_PATH` as a `status: "partial"` skeleton: every key from the
schema in step 9 present, `commits`/`deferred`/`rejected_alternatives`/
`anti_patterns_found` as empty arrays, and a non-empty placeholder
`summary` string (so the skeleton itself validates). After every finding
is processed, refresh that finding's disposition in the artifact with a
short, targeted `Edit` — never a full rewrite. A finding never attempted
because the turn budget ran out is recorded in `deferred[]` with
`reason: "turn-budget — not attempted"` and `tracker_entry_url: ""`.

## 1. Load context

Before drafting any fix, load the inputs:

- Read the PR fetch output the wrapper passed you. Extract: the filtered
  finding set (each entry has `file`, `line`, `end_line`, `label`,
  `decoration`, `confidence`, `subject`, `body`, and an agent category like
  `Bug-Detection`/`Security`/`Pattern-Consistency`/`Performance`/`Supply-Chain`/`Test-Coverage`/`Product`), the
  inline review comments to address (each has `comment_id`, `path`, `line`,
  `body`), and the head SHA captured at fetch time.
- Read `<SKILL_DIR>/references/conventional-comments.md` for the labelling
  vocabulary the inline reply bodies in step 4 must use.
- Read the lens-matching `<SKILL_DIR>/references/checklists/<lens>.md` only if a
  finding's category is unclear and you need to disambiguate (`Bug-Detection` →
  `bug-detection.md`, `Security` → `security.md`, `Pattern-Consistency` →
  `pattern-consistency.md`, `Performance` → `performance.md`, `Supply-Chain` →
  `supply-chain.md`, `Test-Coverage` → `test-coverage.md`, `Product` →
  `product.md`).

This is read-only background — these reads stay in your context.

## 2. Classify each finding (auto-fix vs defer)

You are in **fix-now mode** — you MUST attempt the edits. Specifically:

- Do **not** preemptively decide that a hook, permission rule, or read-only
  filesystem state will block writes. Don't assume one applies; attempt the
  edit and rely on the tool-call result.
- Do **not** infer a block from the worktree path (e.g. `flow-*` worktrees
  are ordinary git worktrees; they have no special write protection).
- Make a real `Edit` / `Write` tool call. If — and only if — the tool returns
  an error, record the verbatim error in the artifact's
  `commits[].tool_error` field (a separate field from `verify_status`,
  which is reserved strictly for `/flow-verify` outcomes; conflating tool
  errors and verify failures into one field made downstream readers
  unable to tell which signal they were looking at). When the tool error
  blocks the entire run rather than a single fix, also surface it as an
  `anti_patterns_found` entry. Either way, surface the error verbatim in
  the return summary.

**Default is fix-now.** Per `AGENTS.md` Hardening: "Fix security, reliability,
and correctness issues immediately — don't defer them." Deferral that lives
only in the artifact is a disappearing-task failure mode unless the artifact
records a concrete tracker entry the wrapper can surface.

For each finding, classify it into one of:

- **Auto-fix (default)** — apply the edit in this run. This is the expected
  path for almost all findings: dead imports/deps, unused files, trivially
  wrong names, missing guards, stale comments, adding a unit test, small bug
  fixes, error-toast additions, etc. If it ships in <30 lines of clear
  changes, fix it.
- **Defer + log** — only when the fix legitimately warrants a separate
  standalone agent session (see bar below). When you defer, you MUST surface
  the deferral in the artifact's `deferred[]` array AND file a durable
  tracker entry. **Default tracker is a GitHub issue** filed via
  `flow-create-issue` (idempotent on title — re-running the address loop
  against the same PR after a re-push reuses the existing open issue):

  ```bash
  mkdir -p "$WORKTREE/.flow-tmp"
  cat > "$WORKTREE/.flow-tmp/deferred-body.md" <<'EOF'
  <file/area + 1-line issue>

  **Why deferred:** <bar criterion>

  - **UX:** <who notices, what changes for them, how often / how much> `[anchor: …]` — or `none`
  - **Problem:** <the concrete failure or friction this removes> `[anchor: …]` — or `none`
  - **Stability/efficiency:** <crash / flake / cost / latency effect, with the reproduced or measured number> `[anchor: …]` — or `none`
  - **Value rank:** <1-5> `[anchor: …]`
  - **Complexity:** <Trivial|Small|Medium|Large> — <files touched, blast radius>
  - **Risk:** <Low|Medium|High> — <review load, regression risk>
  - **If never done:** <what breaks, stays broken, or keeps costing — or `nothing`>
  - **Verdict:** clears bar — <the decisive line>

From gavingolden/flow, MIT.

More from gavingolden/flow