Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 25 additions & 5 deletions plugins/code-tidying/skills/tidy/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,11 @@ Self-review by the producing context is enough here — a fresh-context verifier

### Phase H — Ship

Create the PR (`gh pr create`) with title:
Never call `git commit` or `gh pr create` directly — Phase E already committed the tidyings, so what's left is PR creation, and that has a canonical gate (issue-linkage resolution, injection-safe body assembly, a pre-create check for a valid closing keyword or explicit opt-out) that a bare `gh pr create` skips entirely.

If the `source-control` plugin is installed, invoke `/pull-request create`. Its stage-and-commit step is a no-op here (tree is already clean from Phase E), so it goes straight to rebase-check, issue-linkage resolution, and gated PR creation. Supply it this PR's title and body content — the canonical flow's body template is fixed to Summary + Test plan (`plugins/source-control/skills/pull-request/reference/create.md` §2.4.1), so give it only those two sections; tidy's own audit-trail content goes in a follow-up comment (below), not the PR body:

Title:

```text
<lane-default-type>(<lane-area>): <what was tidied>
Expand All @@ -144,13 +148,29 @@ Examples:
- `docs(skills): repair stale cross-references`
- `chore(tools): apply shellcheck/shfmt drift across tools/*.sh`

PR body sections:
Body sections:

- **Summary** — 1-3 bullets: which lane, which tidyings, anchor commit.
- **Tidyings applied** — table: tidying type → file → line range → LOC delta.
- **Deferred items** — if the scope budget capped the run, link filed issue numbers.
- **Test plan** — verification commands run + results.

`/pull-request create` reports the created `<pr_number>` back on completion (its own §2.6 "Report and stop"). Immediately post one follow-up comment on that PR with `tidy`'s own audit trail — content the canonical body template has no slot for:

```bash
gh pr comment <pr_number> --body-file - <<'EOF'
## Tidyings applied

<table: tidying type → file → line range → LOC delta>

## Deferred items

<links to filed issue numbers, if the scope budget capped the run>
EOF
```

The comment itself is never optional when a PR was created — "Tidyings applied" is never empty at that point (Phase D's empty-PR-avoidance rule means no PR gets created when there's nothing to tidy), and it's the only place this content appears now that the canonical body template has no slot for it. Only the "Deferred items" subsection is conditional: omit it when nothing was deferred, and never post it as an empty table.

If `source-control` isn't installed, apply the same invariants inline: resolve issue-linkage before writing a closing keyword (`Closes #N` only after confirming issue #N exists in this repo — e.g. `gh issue view N`; otherwise state `No related issue: <reason>`), assemble the body via a quoted heredoc (`<<'EOF'`) plus parameter-expansion concat rather than an unquoted `<<EOF` (which would execute any `$(...)` embedded in prompt-derived text), and refuse to call `gh pr create` until the assembled body contains a valid closing keyword or the opt-out marker. In this fallback path only, the Tidyings-applied/Deferred-items sections stay in the PR body itself (there is no canonical gate to conflict with).

Then monitor checks (`gh pr checks <n> --watch`) until green. Address review-bot findings: verify each against the current code — fix the correct ones, rebut the incorrect ones with evidence. **Manual merge by a human** — this skill does NOT auto-merge.

## Global HARD/SOFT EXCLUSIONS
Expand Down Expand Up @@ -185,7 +205,7 @@ Full template: [reference/scope-budget.md](reference/scope-budget.md). Summary:
- Every item the scope budget cuts becomes one filed work item.
- Title format: `<conv-type>(<area>): <what>`.
- Body must include: rationale, file list, scope estimate (LOC + files), and a link to the parent tidy PR.
- The PR body's "Deferred items" section links every filed item by number.
- Phase H's "Deferred items" follow-up comment (or, when `source-control` isn't installed, the PR body's own "Deferred items" section) links every filed item by number.

## Gotchas

Expand Down
4 changes: 2 additions & 2 deletions plugins/code-tidying/skills/tidy/reference/scope-budget.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ When the hunt phase produces more candidates than fit in the budget:

3. **Defer the rest.** For each unselected candidate above a "would-be-worth-doing" threshold (i.e., not trivial micro-tidyings — those just go away), file a work item using the deferred-items template below: via `/work-items:track add` when that plugin is installed, else `gh issue create`, else present the list to the user.

4. **Record the deferred issue numbers in the PR body** under a `## Deferred items` section. This makes the PR's review obvious-by-default: "here's what I did, here's what I parked for next time, here are the issue numbers to hold me accountable."
4. **Record the deferred issue numbers** under a `## Deferred items` section — in Phase H's follow-up PR comment when `source-control` is installed, otherwise directly in the PR body. This makes the PR's review obvious-by-default: "here's what I did, here's what I parked for next time, here are the issue numbers to hold me accountable."

### Greedy vs. optimal selection

Expand Down Expand Up @@ -128,6 +128,6 @@ No upper bound on deferred issues per run. If a single run defers >10 items, tha

1. **Phase D (Hunt + prioritize + scope-budget enforce)** — after building the prioritized findings table, sum the LOC deltas. Apply the greedy selection.
2. **Phase E (Implement)** — periodically check actual LOC delta against the running estimate (`git diff --stat origin/<default-branch>...HEAD`). This measures the full branch diff — all commits since the branch point, not just uncommitted changes relative to HEAD. If actual exceeds estimated by >25%, stop the current tidying mid-flight and re-budget.
3. **Phase H (Ship)** — the PR body's `## Deferred items` section comes directly from this protocol's filed-issue list.
3. **Phase H (Ship)** — the `## Deferred items` section (follow-up comment, or PR body when `source-control` isn't installed) comes directly from this protocol's filed-issue list.

If the cap numbers themselves need to change, that's a research-driven update — not a tidy. See the SELF-UPDATE EXTRA HARD list in `reference/exclusions.md`.
Loading