lfg

# /flow:lfg — $ARGUMENTS `main` below is the default branch: Workflow → Base when set, else `main`. One pass from nothing to a merge-ready PR. The phases are the same everywhere; every fact they act on comes from the repository. **Read `AGENTS.md` first**, its `## Workflow` section above all (Verify, Specs, CI, Review bot, Merge, PR contract, Conflicts, Worktree setup, Release). "Workflow → X" below means that line; a missing line means none. AGENTS.md's never-do rules bind every phase. ## Phase 0: Branch 1. `git fetch origin main` 2. **Already prepared?** An orchestrator (`/flow:follow-through`) may have created the branch in a worktree. Keep it, and say so, only when all hold: `git branch --show-current` is `issue-<number>-…` for this issue, `git status --porcelain` is empty, `HEAD` equals `origin/main`. 3. Otherwise `git switch -c issue-<number>-<slug> origin/main` (`feature/<slug>` without an issue). Works in a worktree too, where `git checkout main` fails. 4. **Machine load.** `ruby ${CLAUDE_PLUGIN_ROOT}/skills/follow-through/load.rb` (add `--max <x>` when Workflow → Agents sets `max load <x>× cores`), now and before each heavy step: the full suite run locally, a system or browser test run, `flow:fable-validator`. `busy` (load more than that many times the cores) → say so once, run tests one file at a time, never two test commands at once, and go on: load slows this run down, never stops it. Any exit but 3 (no `ruby`, a crash) counts as ok. ## Phase 1: Understand - Issue: `gh issue view <n> --json title,body,labels,comments`. Plan file: read it whole. Keep the issue's type/area labels for the PR (Workflow → PR contract says how labels work); never edit the issue's own labels. Note whether the plan has an `## Estimate` (Phase 3). - **One PR per issue.** An umbrella (sub-issues, or task-list items `- [ ] #N`) is not run here: stop and name `/flow:follow-through <n>`, or `/flow:lfg` on its first open child. A plan whose steps would land as several PRs (phases, "one PR per step") is split first: `/flow:plan split <n>` (Skill tool; `--unattended` when an orchestrator runs this) makes #n the umbrella of one sub-issue per PR. Then `git branch -m issue-<first step>-<slug>`; this run takes the first step as `<n>`. - Write acceptance criteria as GIVEN / WHEN / THEN. Do not go on until you can. - Comprehension gate — one line each: the problem; why it matters; what changes for the user; edge cases nobody mentioned; the code path or data flow. Can't answer one → investigate more. - TaskCreate the steps. ## Phase 2: Explore Find the related files (an Explore agent with `model: haiku` for broad sweeps), read how similar features are built, the integration points, and the existing tests. ## Phase 3: Plan Files to change and why; new files; migrations; the tests to write first. A library limitation is never worked around silently: `/flow:plan upstream <owner/repo> <limitation>`, linked from the PR. **Rigor.** Classify the planned files: `printf '%s\n' <planned paths> | ruby ${CLAUDE_PLUGIN_ROOT}/skills/lfg/rigor.rb --files - --summary`. It prints `Rigor: <tier> — <why>` from the rigor file that Workflow → Rigor names in the working tree (there is no diff yet), and `critical` when there is none. Log the line in `implementation-notes.md`, so a critical change is known before the first edit. Phase 6.5 decides on the real diff. **Estimate.** The plan has an `## Estimate`: that is what this PR is measured against. None (a plan written before plans had one, an issue without a plan, a description): write one now, before the first edit, at the top of `implementation-notes.md`, by `../effort/SKILL.md` → The estimate (beside this skill's directory), calibrated as it says. Never revise either after the work starts: the deviation is the measurement. ## Phase 4: Implement (TDD) A bug fix runs Phase 5 first: the root cause decides where the failing test and the fix belong. **Deviation log from the first edit.** The moment reality forces a choice the plan did not settle, add one line to `implementation-notes.md` at the repo root: deviation (planned X, did Y, because Z), discovery (a fact the plan did not know), or judgment call (a choice the user might have made differently). Take the conservative option and keep going. Never commit the file. Per logical unit: a failing test first (run it, see it fail for the right reason) → the minimum code to pass → refactor green → Workflow → Verify on the changed files. `/flow:tdd` is the long form. ## Phase 5: Root cause (bug fixes — before Phase 4) Trace the failing value back to where it was created; `git log -S` / `git blame` for why the code is the way it is; map every caller; five whys to the earliest point the error could be prevented, and fix there. Never `rescue nil`, a blind `&.`, a presence guard, `find` → `find_by`, or an early return that hides the cause. ## Phase 6: Verify All of Workflow → Verify, and the local gate of `/flow:tdd` → Done: the tests for what changed (Workflow → Specs → changed, else each changed file's tests) when CI runs the full suite, else the full suite. Then re-read the request: would the requester call it done; is it the root cause; do the tests prove it? ## Phase 6.5: Fable validation by rigor **The tier.** Run `ruby ${CLAUDE_PLUGIN_ROOT}/skills/lfg/rigor.rb --base origin/main --summary --labels <the issue's labels, comma-separated>`. It prints `Rigor: <tier> — <why>`. The tier is the highest that any changed path, added-line signal or label reaches in the rigor file that Workflow → Rigor names, both read at the merge base, so a change never chooses its own gate. A change that touches that rigor file, adds or removes a Rigor line in AGENTS.md, or leaves a Workflow Rigor line naming another file or none, is critical (`config`). When the base has no Rigor line or lacks its file (first adoption), the working tree's is read, with a warning, and the change is critical too. Every unknown state prints `critical`: no Rigor line, a bad rigor file, or a git error. **Overrides.** - `--rigor <tier>` in the arguments raises the tier. - A `--rigor` below the computed tier needs `--why "<reason>"`. The PR body then reads `Rigor: <lower> (lowered from <computed>: <reason>)`. - Under `/flow:follow-through` the tier is never lowered. **Why tiers.** The second model's value is its first read of the change. Re-reading a fix of its own notes costs as much and rarely finds anything new, so only critical changes pay for it. | Tier | The validator | |---|---| | **light** | None. Workflow → Verify and the review bot are the gate. | | **standard** | One pass. PASS WITH NOTES → fix each note you agree with (failing test first for code) and rebut the rest in one line each in the PR body. **No re-run.** | | **critical** | The full loop. BLOCK or PASS WITH NOTES → fix every blocker and note (failing test first) and run it again. A factually wrong note gets a one-line rebuttal in the PR body. Nothing is accepted as a risk or deferred. | **Running it, standard and critical.** - Spawn `flow:fable-validator` with the issue, the acceptance criteria, the base branch and the tier. - On either tier, BLOCK → fix every blocker (failing test first) and run it again. A blocker you dispute gets a one-line rebuttal in the PR body instead of a fix, and the validator runs again. - The loop ends on PASS. It also ends on a PASS WITH NOTES whose notes you rebutted without changing code, which on critical means every note was rebutted. - Stop after three answers that each made you change code, or after three BLOCKs in a row, whichever comes first: - an answer that made you change code is a BLOCK you fixed or, on critical, a PASS WITH NOTES whose notes you fixed; - a BLOCK answered without a code change, such as a rebuttal, still counts toward three in a row, so a disputed BLOCK cannot loop. Then ask (interactive) or park (orchestrator). - On standard and critical, no PR before PASS or PASS WITH NOTES with every note fixed or rebutted. Light opens its PR after Workflow → Verify, with no validator. **The PR body** carries: - the `Rigor:` line; - on standard and critical, `Validator: <verdict> at <short head sha>` and the validator's "Not verified" list. On standard, fixing a PASS WITH NOTES note changes code after the validated sha. Commit the fixes, then append `, notes addressed at <short sha of that commit>` to the line. That later sha is the one `/flow:finish-prs` measures code changes from. `/flow:finish-prs` reads both lines. ## Phase 7: Commit and PR Conventional commit (`feat(scope): …`), body says why. Push with `-u`. `gh pr create` with the labels from Phase 1 and every section Workflow → PR contract requires, in its order, plus Phase 6.5's `Rigor:` and `Validator:` lines. The issue this run implements closes with the PR: `Closes #<n>` in the body (one PR per issue, Phase 1); `Refs #N` only for other issues it touches. The body ends with `## Deviations & judgment calls`, copied from `implementation-notes.md`'s log, not its estimate ("None — the plan held." if empty). Then `/flow:effort <PR> --write` (Skill tool; add `--estimate <file>` naming where the estimate is when it is not on the issue: the plan file you ran, or `implementation-notes.md` when Phase 3 wrote it): it puts `## Effort & cost` before the deviations, and you write its **Where it went** line when a row is outside the estimate. Then delete `implementation-notes.md` (never the plan file). A UI change attaches before/after screenshots (`gh pr comment <n> --attach '<file>#<alt>'`) when the PR contract asks for them. ## Phase 8: Finish the PR — never merge Run `/flow:finish-prs <PR>` (Skill tool) in its default mode: merge main in, then rounds of conflicts → CI → every review thread (the review bot's included), waiting on CI and the bot between rounds, until merge-ready. Every finding is fixed or answered in its round. `/flow:lfg` never merges: the user does. Only an orchestrator's brief (`/flow:follow-through`) runs this phase as `/flow:finish-prs <PR> automerge`. A blocker outside the repository ends the phase: name it and what removes it. ## Phase 9: Close-out End the final message with: 1. **The decisions, not the diff** — the 3–5 non-obvious choices someone maintaining this must know, deviation-log items first. 2. **Three merge-gate questions** the user should be able to answer before merging; offer a walkthrough if any is not obvious. 3. **The umbrella, when this is its last open child.** Its parent (`gh api 'repos/{owner}/{repo}/issues/<n>/parent' --jq .number`, 404 = none), else the first `#N` after `Part of`. When `gh api 'repos/{owner}/{repo}/issues/<umbrella>/sub_issues' --jq '[.[] | select(.state == "open" and .number != <n>)] | length'` prints 0, merging closes the issue but not the umbrella: give `gh issue close <umbrella> --comment "<#N → #pr per child>"`. Under `/flow:follow-through`, leave it out: the orchestrator closes it.