Skip to content

docs(skill): PR lifecycle discipline - fold-first, rebase cadence, closure conventions #2055

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jaylfc merged 1 commit into from
Jul 19, 2026
Merged

docs(skill): PR lifecycle discipline - fold-first, rebase cadence, closure conventions #2055

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
54 changes: 54 additions & 0 deletions .claude/skills/taos-development-skill/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,60 @@ findings **before** surfacing the PR for human maintainer review.
| WARNING | Must fix before blocking for review |
| SUGGESTION | Fix or explain why not applicable |

## PR lifecycle discipline (fold-first, rebase, closures)

The review pipeline only works if the open-PR set stays small and every finding
gets closed out. These rules are load-bearing; the maintainer gates on them.

### Fold-first: findings outrank new work

If ANY of your open PRs has an unaddressed maintainer fold list or bot finding,
addressing it comes BEFORE opening a new PR. Priority order each work session:

1. Fold open findings on existing PRs (maintainer comments first, then bot findings).
2. Rebase any of your PRs that show CONFLICTING against the base branch.
3. Only then start a new slice.

A finding folded within hours merges the same day; a finding left while you open
new PRs stalls the whole train behind it (the maintainer will not merge past an
open finding, ever).

### Rebase cadence and the stale-base rule

- dev moves fast. When your PR shows CONFLICTING, rebase onto current dev
promptly - a CONFLICTING PR is invisible to the merge queue.
- A green CI run computed BEFORE the base branch moved is STALE. Two individually
green PRs can conflict semantically with zero textual conflict (see the
#2009/#1932 App-key incident, fixed in #2041). If dev advanced since your last
CI run, rebase (or push an empty commit) so CI re-runs against the current base
before asking for merge.
- Keep your open-PR count small (aim under 10). A wide-open set guarantees most
of it is permanently CONFLICTING and re-review effort is wasted.

### Closing PRs: always link the successor

Never close a PR silently. In the closing comment state exactly one of:

- "Superseded by #NNNN" (and confirm every still-open finding from this PR is
in the successor's scope), or
- "Landed via #NNNN" (when the content merged through another PR), or
- "Abandoned because <reason>".

A close without a successor link reads as lost work and forces the maintainer
into git forensics (this happened with #1927/#1924 - both were legitimate
"landed via" closures that looked like data loss for hours).

### One PR per slice

- A fix and the test that proves it belong in ONE PR (pitfall 13 in

@kilo-code-bot kilo-code-bot Bot Jul 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WARNING: Reference to docs/contributor-pitfalls.md (and "pitfall 13") may be an unreachable path/number.

This section instructs agents to read docs/contributor-pitfalls.md and cites "pitfall 13". I was unable to verify the file exists at that exact path or that the pitfall numbering matches (the sandbox blocked the verification API calls). If the path is wrong (e.g. it lives under a different directory) or the numbering has drifted, the instruction silently breaks and agents won't find the referenced items. Please confirm the path resolves from repo root and that pitfall #13 is in fact the fix-and-test-in-one-PR item; consider linking the absolute repo path or a heading anchor instead of a bare relative path.

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

docs/contributor-pitfalls.md).
- Never open a sibling PR for a slice that already has one. If a fresh branch is
genuinely needed, open the new PR, link it, and close the old one with the
supersede note in the same action.

Read docs/contributor-pitfalls.md before every PR - fold lists reference its
items by number (for example "pitfall 5").

## Common fix patterns

- **New route:** `routes/<feature>.py` with `router = APIRouter()` → register in
Expand Down
Loading