pr-loop

Files (1)

• SKILL.md

SKILL.md (first lines)

# /pr-loop

Deliver one backlog item per iteration. Subagents run sequentially (implement → cleaner → review → correct). The main agent owns product verification, `pr-description` draft and publish, push, rebase, force-push, merge, and GitHub. Subagents write code and create local commits.

## Invariants for each iteration

1. Merging requires authorization. Requesting the loop authorizes work through opening a PR. Each merge requires authorization in the conversation unless the operator approved the entire batch beforehand (for example "merge everything").
2. Author and committer are always the human operator (`git config user.name` / `user.email`). Never set `--author` or `GIT_AUTHOR_*` / `GIT_COMMITTER_*`. Provenance is owned by `../publication-hygiene/SKILL.md`.
3. Tests and typecheck must pass before each commit. Discover the commands in step 0. If a package has no tests, the implementer adds them following the repo's conventions.
4. Worktrees stay on disk at `~/.cache/worktrees` (not `/tmp`). A worktree can be resumed across sessions; its branch must be on origin before the iteration is finished. Resume with `git worktree add -b <branch> ~/.cache/worktrees/<slug> origin/<branch>`, or start from `origin/main` when no remote branch exists. Some linters skip that path: Biome with `!**/.cache` processes no files, so `pnpm run lint` and a husky pre-push hook fail. When step 0 finds the lint processing no files, recreate the worktree at `~/worktrees/<slug>` and use it for the whole iteration.
5. Use `gh-axi` for GitHub. Read TOON output without piping it to jq.
6. Follow the target project's language conventions for commits, PRs, docs, comments, and UI strings. Conversation uses the user's language. For PT-BR prose, apply `../unslop-br/SKILL.md`. For English prose, apply `../humanizer/SKILL.md`. PR bodies follow `../pr-description/SKILL.md`. Do not apply Portuguese vocabulary rules to other languages.
7. For checks through rtk, use `pnpm -C <pkg> <script>`. rtk does not yet forward `--filter` to `tsc`; `pnpm --filter <pkg> <script>` can run the compiler at the monorepo root, print help, and exit 1 as a false typecheck failure. A subagent interrupted by a usage limit or timeout may leave completed work uncommitted: inspect `git status` and `git diff` before starting over.

## When subagents are unavailable

If usage limits, missing subagent tools, or a persistent subagent failure prevent delegation, run steps 1 through 4 in the main conversation, including the cleaner correction pass, product verification, and `pr-description` drafts. Review the full diff, verify in the code the facts assumed by the tests (helpers, seeds, counts), and audit each quoted passage before committing.

## Step 0, prepare the item

- Take the items from the operator's list or the target repo's local tracker on the **primary worktree** (`<primary>/.scratch/<feature>/issues/`). Confirm the list and order before the first iteration.
- Run `git fetch origin` and create a clean worktree with `git worktree add -b feat/<slug> ~/.cache/worktrees/<slug> origin/main`. If a leftover worktree exists from a previous iteration, enter it and inspect `git status` and `git log --oneline -3`.
- Discover the validation commands in each affected package.json (test, typecheck, lint). Include them in every subagent prompt, including a possible cleaner correction pass.
- Record the iteration base SHA before implementation; keep it fixed through correction commits.
- Define the scope, exclusions, and completion criteria in a few sentences.
- Define the **product behavior to prove** after implementation: UI route/flow, API, CLI scenario, or N/A for docs/chore with no runtime surface. Record how success looks (observable result, not only "tests pass").
- For visual UI work, capture **before** from the base revision (`origin/main` or the PR base) or reuse an identified earlier capture. Do this before the implementation commit, or from a separate checkout of the base. After implementation, capture **after** on the feature branch. Label each file.
- Establish the language for each output from the project's instructions and existing files or commit history. Pass that choice to every subagent.

## Step 1, implementation subagent

The subagent starts without context, so the prompt must be self-contained:

```
Implement [DEFINED SCOPE] in repository [WORKTREE PATH], branch [BRANCH].
Do not push, rebase, or touch other repositories.

CONTEXT: [repo stack in 2-4 lines: language, framework, persistence,
what the affected subsystem does and how. Key files with paths.]

REQUIREMENTS:
- [numbered, verifiable items, with target files when known]
- Tests: [what to cover, following the repo's pattern in ...]

STYLE: follow the repo's conventions; read neighboring files before writing.
Language for comments, docs, UI strings, and commits: [project conventions].
Apply [../unslop-br/SKILL.md for PT-BR | ../humanizer/SKILL.md for English].

REQUIRED CHECKS before committing: [test and typecheck commands]. Fix failures.
COMMIT: one local commit; repo log language and style; git config author; never --author.
FINAL REPORT: changes by file, test counts, commit hash, omitted work with reasons.
```

## Step 2, clean-crap gate (main agent)

Run `../clean-crap/SKILL.md` against the worktree. Resolve `<clean-crap>` as the `clean-crap` folder next to this skill. Select the committed iteration diff and any uncommitted changes with `--since <BASE_SHA>`:

```
node <clean-crap>/scripts/clean-crap.mjs --root <WORKTREE> --since <BASE_SHA> [--threshold N]
```

- Exit 0: confirm the report accounts for the iteration's changed JS/TS sources and each analyzed function has numeric CRAP before advancing. For a slice with no eligible JS/TS sources, record N/A.
- Exit 2: run the correction pass below before product verification or review.
- Exit 1: fix the invocation or environment. A syntax error in changed sources goes back to the implementation scope. Never advance past the cleaner while the gate errors.

If the gate reports no LCOV and step 0 discovered a coverage command, run that command once and re-run the gate. Null CRAP means the threshold was not evaluated, including when coverage is missing for only some functions. When coverage cannot be supplied, report complexity as measurement only and obtain an explicit cleaner skip for this slice. Add `.metrics/` to the target project's ignore rules in the next correction commit when missing.

### Correction pass after exit 2

Delegate a focused fix subagent, then re-run the project's tests and the gate:

```
Lower CRAP in worktree [WORKTREE], branch [BRANCH].
Do not push, rebase, or touch other repositories.
The clean-crap gate failed threshold [N]:

[FAILURE LIST from stdout: name, namespace, CRAP]

Full report: <worktree>/.metrics/crap.json (never commit this file).

Lower CRAP by splitting the named functions into smaller units or
removing redundant branches; behavior must not change. Where splitting
is not enough, add tests that exercise the uncovered branches to raise
coverage. Run the gate again to confirm.

REQUIRED CHECKS before committing: [commands]. Fix failures.
COMMIT: one local commit, repo language and style, git config author.
FINAL REPORT: failing entries before and after, test counts, commit hash.
```

Allow at most two correction rounds per iteration. On the third gate failure, stop and escalate to the operator with the failure list; the operator may skip the gate for this slice or set a different threshold. Never weaken the gate silently.

### Skipping the cleaner

When the operator explicitly asks to skip the cleaner for a slice, record the skip in the conversation and the iteration report, then advance to step 2a.

## Step 2a, product verification (main agent)

Run the product behavior planned in step 0. This is separate from unit/typecheck commands.

- UI: exercise the changed flow end to end with the available browser/preview tools. Capture **after** on the feature branch and pair it with the **before** capture from step 0. If before is missing, check out the base revision in a separate worktree (or stash, capture, restore). A screenshot taken after implementation is not before.
- API/CLI: run the concrete command or request that proves the behavior; keep exit code and relevant output.
- N/A: for docs/chore with no runtime surface, record that verification is not applicable and skip capture.

Do not invent a green result. On failure, fix in scope (return to implementation or a focused correction) before drafting the PR body. Do not advance to 2b while the scenario failed. Keep temp media for the draft/publish path; do not commit it.

## Step 2b, PR description draft (main agent)

Follow `../pr-description/SKILL.md` in **draft** mode. Write `<worktree>/.scratch/pr-description/body.md` from the diff and the observed checks from steps 1–2a. Pass that path to the reviewer in step 3.

## Step 3, review subagent (read only)

One subagent reviews both code and prose.

```
Perform a READ-ONLY senior review (no edits or commits) of PR [N] /
diff [main...branch] in repository [WORKTREE].
Diff: git -C [WORKTREE] diff main...[BRANCH]. PR body: [local copy file].
Commits: git -C [WORKTREE] log main..[BRANCH].

From pedrosatin/skills, MIT.

More from pedrosatin/skills