/finn-build

name: finn-build
description: Claim the next safe agent-ready issue from Linear, implement it, and open a PR. Use when asked to run Finn-loop's builder, work the approved queue, or fix Finn-loop review feedback. Designed for /loop; one pass does one unit of work.

Finn-loop builder

One pass = one unit of work: fix review feedback on one existing PR, or build one issue end to end. Under `/loop`, each iteration runs this skill once.

0. Preflight

Before changing Linear, GitHub, branches, or files:

• Confirm this is the intended GitHub repository and `origin` is reachable.
• Detect the repository's default branch with

`gh repo view --json defaultBranchRef --jq .defaultBranchRef.name`; never assume it is `main`.

• Require a clean working tree (`git status --porcelain` must be empty). If it

is dirty, report the paths and end the pass. Never stash, reset, overwrite, or commit unrelated work.

1. Review feedback first

List open PRs labeled `loop-changes-requested`, including their labels:

gh pr list --state open --label loop-changes-requested --json number,title,headRefName,headRefOid,labels,updatedAt,url

Skip every PR carrying `needs-human-review`; it has left the automated repair queue until a human resolves the escalation.

If any PR remains, choose the least recently updated one. Read its linked Linear issue and latest `Finn-loop review of COMMIT_SHA` verdict. Check out its branch, fix only the "Must fix before merge" items, run the relevant checks, push, remove `loop-changes-requested`, and comment with what changed. End this pass.

If a proposed fix would cross an issue non-goal or requires a product decision, do not implement it. Comment the exact conflict, add `needs-human-review`, remove `loop-changes-requested`, and end the pass. This prevents the next loop iteration from retrying a decision only a human can make.

2. Pick

Using the Linear connector, list issues on team `TEAM` that meet every condition:

• labeled `agent-ready`
• unassigned
• not labeled `blocked`
• no unresolved blocker relation

Sort by priority, then oldest first. If the queue is empty, say so and end the pass. Do not invent work and do not pick a blocked issue.

3. Claim (the cooperative lock)

Assign yourself and move the issue to the team's started workflow state (prefer `In Progress` when available). Claim before reading deeply or writing code. Re-fetch the issue immediately after the update; if it is blocked, assigned to somebody else, or no longer `agent-ready`, do not work it and return to step 2.

The assignee prevents different people from taking the same issue. It is not an atomic lock between simultaneous sessions authenticated as the same Linear user, so only one builder loop may run per team.

4. Read

Fetch the full issue including comments and relations. Implement only its acceptance criteria. Non-goals are binding. Compare every `AC-N` against every `NG-N` before editing. No unrelated changes and no opportunistic refactors.

If an acceptance criterion is ambiguous, conflicts with a non-goal, or depends on an unresolved blocker, go to step 8. Never guess.

5. Build

• Fetch the latest default branch from `origin` and create or resume a branch

named `TEAM-NNN-short-slug`, using the issue's real identifier.

• Implement the acceptance criteria using the repository's existing style,

architecture, and naming.

• Add or update tests when the change affects logic, data flow, permissions,

integrations, or user-visible behavior.

• Preserve behavior outside the issue contract.

6. Verify

Run the project's relevant lint, typecheck, build, and narrowest useful tests. All checks attributable to this change must pass before opening a PR. If a broad check has a pre-existing unrelated failure, run the relevant targeted check, preserve the evidence, and disclose both results in the PR.

Review `git diff` and `git status` before shipping. Stop if the diff contains unrelated work or generated secrets.

7. Ship

Push and open a PR with `gh pr create`. Its description must include:

• What changed and why
• `Closes TEAM-NNN`, using the real Linear issue identifier
• A scope ledger: one evidence line per `AC-N`, one preservation line per

`NG-N`, and `Other behavior changes: None`

• Numbered manual test steps matching what was actually built
• Automated checks run and their results
• Risk: Low / Medium / High

If `Other behavior changes: None` is not true, stop and get the Linear issue amended before opening the PR.

Comment the PR URL on the Linear issue. Move it to the team's review state if one exists; otherwise leave it in the started state for the Linear-GitHub integration to manage. Never merge and never enable auto-merge. End the pass.

8. Blocked

Comment one specific question a human can answer asynchronously, apply the `blocked` label, and unassign yourself. Leave `agent-ready` in place: the pick query explicitly excludes `blocked`, so the issue safely reappears only after a human answers and removes that label.

Never use "this is unclear" as the question. State the exact decision, the available options, and which acceptance criterion it affects. End the pass so the next iteration can pick different work.