Refresh stack workflow#66
Conversation
|
Warning Review limit reached
Next review available in: 58 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Enterprise Run ID: 📒 Files selected for processing (14)
WalkthroughIntroduces the Changesrebase-stack Workflow Introduction
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested labels
Suggested reviewers
Poem
Important Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (2 errors, 1 warning)
✅ Passed checks (9 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
asafbennatan
force-pushed
the
refresh-stack-workflow
branch
8 times, most recently
from
7f8ee72 to
f9d7b2f
Compare
adalton
left a comment
adalton
left a comment
There was a problem hiding this comment.
General comment on scope
The conflict guidance, fork-aware PR fallback, and the --ours heuristic for stacked rebases are genuinely useful knowledge to capture. But I'd push back on whether this needs to be a full workflow with 4 phases, a controller, validation cache, worktree management, and parallel execution.
gh-stack already handles the mechanical parts — cascading rebases (gh stack rebase), atomic pushes (gh stack push), and even the combined operation (gh stack sync). The user working with stacked branches is already sophisticated enough to run these commands. The AI value-add here is thin compared to workflows like implement or e2e, where the agent is guiding hours of complex judgment calls. Here, the underlying operation is 2-3 shell commands plus conflict resolution if needed — the complexity is low regardless of how frequently you rebase.
Per-branch validation with worktrees duplicates what CI does once the PRs are pushed. The validation cache is clever engineering for a problem that doesn't justify it — if lint/tests are fast enough to run locally, the cache isn't needed; if they're slow, you're better off letting CI handle it after push.
I'd suggest capturing the useful parts — conflict resolution strategy, the --ours heuristic for stale-copy conflicts, fork-aware PR creation — as a recipe in _shared/ or a section in the implement/e2e guidelines, rather than a standalone workflow.
If the workflow does move forward, issues to address:
-
commands/start.mddescription says--update-refsbut the implementation usesgh stack rebase— these are different mechanisms (native git vs. gh-stack extension). Same issue in the top-levelREADME.mdentry. -
AGENTS.md phase listing says
(start, continue, push)but is missingvalidate. -
Controller doesn't direct the agent to read
guidelines.md— SKILL.md references it for safety rules, but the controller (which commands dispatch to) never tells the agent to read it. An agent going through command → controller → skill would skip the safety rules entirely. -
gh-stackis in private preview — the extension installs, but the underlying Stacked PRs feature requires repo-level enablement. The README lists it as a prerequisite without mentioning this constraint. Users who install it and find it non-functional will have no explanation. -
commands/push.mddescription says "Review updated branches" — push doesn't review anything; that's validate's job.
the main advantage of just using gh stack is the intermediate validate phase which we can expand or make pluggable as we want - this allows confidently rebasing the entire stack knowing that rebased merges actually work (not that they just dont have conflicts) |
|
That's a fair point — clean rebase doesn't mean the code still works, and catching silent breakage before push is a real gap in vanilla My concern is more about packaging than value. The start/continue/push phases are thin wrappers around The 5 issues in my earlier comment would still apply either way — worth addressing regardless of the final shape. |
|
before i address this i just want to understand that we agree that this flow should be added , |
|
regarding this :
this workflow adds alot of value even without the private preview enabled on target repo , when preview enabled gh interface shows stacked PRs natively and gh stack submit creates a suitable PR stack , currently we fallback to creating the prs ourselves which still adds alot of value since we rebase and validate all . i am currently using this flow (from my branch ) and i find it extremely useful |
|
Yes, I agree the workflow brings value — the orchestration of rebase → conflict resolution → per-branch validation → push is genuinely workflow-shaped, and validating each branch independently before pushing catches problems that On the private preview point: you're right, the CLI works without the server-side feature and the fallback to manual PR creation handles it. Worth a brief note in the README prerequisites so users aren't surprised, but it's not a blocker. To get this mergeable, I'd suggest we simplify a couple of things. We can always add them back later if experience shows they're needed: Simplify:
Fix:
|
|
done - note that i have preferred to keep the validation cache but simply do not clear it on start - as it already contains specific SHAs it will never be stale , this is required incase you have to fix stuff in a middle brunch and have to re-run validate |
|
Thanks for the updates — everything looks good except one leftover: the top-level |
|
fixed @adalton |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
rebase-stack/guidelines.md (1)
1-42: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd explicit Principles and Quality sections.
The file covers Safety Rules, Conflict Handling, and PR Creation well, but lacks explicit Principles and Quality sections (or equivalent coverage). As per path instructions, guidelines.md must contain Principles, Hard Limits, Safety, Quality, and Escalation sections.
Suggested additions:
- Principles: e.g., "Prefer atomic operations over partial updates", "Preserve stack ordering integrity", "Never rewrite history without explicit user confirmation."
- Quality: e.g., "Every branch must pass the project's lint and unit test suite before it is pushed. Validation failures block push for that branch and all branches above it."
This aligns the file with the canonical guidelines structure used by other workflows in this repository.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@rebase-stack/guidelines.md` around lines 1 - 42, The guidelines document is missing the required Principles and Quality sections, so update the top-level structure in guidelines.md to include those sections alongside the existing Safety Rules, Conflict Handling, and PR Creation content. Add a Principles section using the unique stack-workflow rules already implied here (atomic operations, preserve stack ordering integrity, never rewrite history without explicit user confirmation) and add a Quality section that requires lint and unit tests to pass before any branch is pushed, blocking the branch and anything above it on failure. Keep the existing guidance but reorganize it to match the canonical guidelines structure.Source: Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@rebase-stack/skills/continue.md`:
- Around line 22-23: The `gh stack rebase --continue` step in `continue.md` only
covers the conflict case, but it needs an explicit non-conflict failure path
too. Update the instructions around `gh stack rebase --continue --remote origin`
so that if the command exits non-zero for reasons like no rebase in progress,
network failure, or unexpected git state, the agent must stop immediately,
report the failure, and not attempt further continuation steps. Keep the
guidance tied to the `gh stack rebase --continue` workflow so the fallback is
clear when conflicts are not the cause.
In `@rebase-stack/skills/controller.md`:
- Line 38: The reference to guidelines.md in controller.md is using the wrong
relative path, which breaks when the workflow is installed via symlink. Update
the instruction in controller.md to reference the parent-directory location of
guidelines.md using a path relative to controller.md itself so it resolves
correctly in all installs.
In `@rebase-stack/skills/push.md`:
- Around line 47-53: The exit handling for gh stack submit --auto is incomplete
because it only covers success and exit code 9, leaving other non-zero failures
ambiguous. Update the instructions in push.md to explicitly state that any
non-zero exit other than 9 must stop execution and report the failure instead of
proceeding to manual PR creation. Keep the behavior tied to gh stack submit
--auto so the agent knows only exit code 0 proceeds, 9 falls through, and all
other failures are terminal.
In `@rebase-stack/skills/start.md`:
- Around line 16-21: The installation step for gh-stack in the skill document
lacks a defined failure mode, so update the instructions around gh extension
install github/gh-stack to explicitly say that if installation fails for any
reason, the agent must stop, report the failure, and not continue with git
configuration or later steps. Make sure the guidance in the relevant skill
section clearly names the install command and states the required action on
failure.
- Around line 46-48: The `gh stack view` exit handling in `start.md` only covers
exit codes 0 and 2, so add explicit guidance for any other non-zero exit code.
Update the step that branches on `gh stack view` results to say that unexpected
failures should stop the process and be reported/escalated rather than assuming
a stack state. Keep the existing 0/2 behavior for stack already exists and not
in a stack, and add a clear fallback for all other codes.
- Line 127: The agent-fix path in start.md is inconsistent with the matching
path in continue.md, so align the instruction text used by the skill docs.
Update the guidance around the “all files are resolved and staged” flow in
start.md to match the continue.md wording for the same operation, using the same
command reference consistently in both places.
- Around line 65-79: The gh stack init section in the start.md skill is missing
a failure-mode instruction for stack initialization. Update the instructions
around gh stack init and gh stack view so that if gh stack init fails for any
reason (missing base, bad branch names, nonexistent branches), the agent must
stop immediately and report the failure instead of continuing; keep the guidance
tied to the gh stack init workflow so it’s easy to find even if the surrounding
text moves.
In `@rebase-stack/skills/validate.md`:
- Line 140: The validation log path in the workflow still uses an absolute /tmp
location, which must be replaced with a repo-root-relative artifact path. Update
the validation command in validate.md to write logs under
.artifacts/rebase-stack/logs/ using the existing {branch-safe-name} pattern, and
make the same path change in the Step 6 and Step 7 references so all log capture
locations stay consistent and relative.
---
Outside diff comments:
In `@rebase-stack/guidelines.md`:
- Around line 1-42: The guidelines document is missing the required Principles
and Quality sections, so update the top-level structure in guidelines.md to
include those sections alongside the existing Safety Rules, Conflict Handling,
and PR Creation content. Add a Principles section using the unique
stack-workflow rules already implied here (atomic operations, preserve stack
ordering integrity, never rewrite history without explicit user confirmation)
and add a Quality section that requires lint and unit tests to pass before any
branch is pushed, blocking the branch and anything above it on failure. Keep the
existing guidance but reorganize it to match the canonical guidelines structure.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 09098d98-3f57-4d2a-808f-d9fd90cb4550
📒 Files selected for processing (14)
AGENTS.mdREADME.mdrebase-stack/README.mdrebase-stack/SKILL.mdrebase-stack/commands/continue.mdrebase-stack/commands/push.mdrebase-stack/commands/start.mdrebase-stack/commands/validate.mdrebase-stack/guidelines.mdrebase-stack/skills/continue.mdrebase-stack/skills/controller.mdrebase-stack/skills/push.mdrebase-stack/skills/start.mdrebase-stack/skills/validate.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (11)
**/{SKILL.md,guidelines.md,skills/*.md,commands/*.md}
📄 CodeRabbit inference engine (Custom checks)
Flag any absolute filesystem path in markdown files within workflow directories (*/SKILL.md, /skills/.md, /commands/.md, */guidelines.md). Paths like /home/, /Users/, /tmp/, /var/, /opt/ are prohibited because workflows are installed via symlink and must use relative paths only. Paths inside fenced code blocks that are clearly examples (containing "example", "e.g.", or placeholder usernames like /home/user/) are exempt.
Files:
rebase-stack/guidelines.mdrebase-stack/skills/validate.mdrebase-stack/commands/continue.mdrebase-stack/commands/validate.mdrebase-stack/skills/controller.mdrebase-stack/SKILL.mdrebase-stack/commands/start.mdrebase-stack/commands/push.mdrebase-stack/skills/push.mdrebase-stack/skills/continue.mdrebase-stack/skills/start.md
**/{SKILL.md,guidelines.md,controller.md}
📄 CodeRabbit inference engine (Custom checks)
When any of SKILL.md, guidelines.md, or controller.md in a workflow is changed, compare it against whichever of the other two files are present and check for verbatim duplication of multi-line instruction blocks or paragraphs. Each has a distinct role: SKILL.md is the thin entry point, guidelines.md holds principles/limits/safety/quality/escalation, controller.md manages phase dispatch. Phase names and brief one-line descriptions appearing in multiple files is EXPECTED (cross-referencing, not duplication) — only flag substantial blocks of identical prose or step-by-step instructions that are copied between files.
Files:
rebase-stack/guidelines.mdrebase-stack/skills/controller.mdrebase-stack/SKILL.md
**/*.md
📄 CodeRabbit inference engine (Custom checks)
For any changed markdown file in a workflow directory, verify that file path references (backtick-quoted paths like
../skills/controller.mdorguidelines.md) point to files that exist. Flag references to files that don't exist (dangling references). Also flag skill or command files that exist but are never referenced from SKILL.md, controller.md, or any command file (orphaned files).
**/*.md: Workflow content must use plain markdown only; do not use IDE-specific syntax.
All file references in workflow documents must be relative to the file's location.
Cross-cutting workflow resources must live in_shared/and be referenced by relative path.
Files:
rebase-stack/guidelines.mdrebase-stack/skills/validate.mdrebase-stack/commands/continue.mdrebase-stack/commands/validate.mdrebase-stack/skills/controller.mdrebase-stack/SKILL.mdREADME.mdrebase-stack/commands/start.mdAGENTS.mdrebase-stack/commands/push.mdrebase-stack/README.mdrebase-stack/skills/push.mdrebase-stack/skills/continue.mdrebase-stack/skills/start.md
⚙️ CodeRabbit configuration file
**/*.md: Cross-workflow consistency (ai-workflows conventions):
- All file references must be relative paths (never absolute) —
this is critical for symlink compatibility- No IDE-specific syntax (Cursor-specific, VS Code-specific, etc.)
- Consistent terminology within a workflow: pick one term, stick
with it- Schema field names and types must match between producer and
consumer files (e.g., if a field is defined in one phase skill
and consumed in another, names and types must agree)- No verbatim duplication of multi-line instruction blocks
across SKILL.md, guidelines.md, and controller.md — each has
a distinct role (shared phase names and brief references are
expected cross-referencing, not duplication)
Files:
rebase-stack/guidelines.mdrebase-stack/skills/validate.mdrebase-stack/commands/continue.mdrebase-stack/commands/validate.mdrebase-stack/skills/controller.mdrebase-stack/SKILL.mdREADME.mdrebase-stack/commands/start.mdAGENTS.mdrebase-stack/commands/push.mdrebase-stack/README.mdrebase-stack/skills/push.mdrebase-stack/skills/continue.mdrebase-stack/skills/start.md
**
⚙️ CodeRabbit configuration file
**: # AGENTS.mdThis file provides guidance to AI coding assistants when working with this repository.
Project Overview
This repository contains reusable AI coding workflows that can be installed globally or per-project in any environment (Cursor, Claude Code, Gemini). Each workflow is a self-contained directory with structured markdown files that AI agents can read and execute.
Current workflows:
- ai-ready — Codebase scanning and AGENTS.md generation (update)
- bugfix — Systematic bug resolution (assess, reproduce, diagnose, fix, test, review, document, pr)
- code-review — AI-driven code review with human-in-the-loop decisions (start, continue, clean)
- cve-fix — Automated CVE remediation from Jira tickets (start, scan, patch, validate, pr, backport, close)
- design — Design-and-decompose workflow (ingest, research, draft, decompose, revise, publish, respond, sync)
- docs-writer — Documentation creation workflow (gather, plan, draft, validate, apply, mr)
- e2e — Story-to-tests workflow for [QE] stories (ingest, plan, revise, code, validate, publish, respond)
- implement — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond)
- kcs — KCS Solution article workflow (gather, draft, validate, handoff)
- prd — Requirements-to-PRD workflow (ingest, clarify, draft, revise, publish, respond)
- sizing — Pre-cycle Feature sizing with T-shirt sizes and team effort breakdowns (ingest, assess, apply)
- skill-reviewer — Meta-workflow that audits AI skill directories
- triage — Bulk Jira bug triage with AI-driven categorization and HTML reports
Architecture
Workflow Structure
Every workflow follows this canonical structure:
workflow-name/ SKILL.md # Entry point with YAML frontmatter (name, version, description) guidelines.md # Behavioral rules: principles, hard limits, safety, quality README.md # Human-readable documentation (prerequ...
Files:
rebase-stack/guidelines.mdrebase-stack/skills/validate.mdrebase-stack/commands/continue.mdrebase-stack/commands/validate.mdrebase-stack/skills/controller.mdrebase-stack/SKILL.mdREADME.mdrebase-stack/commands/start.mdAGENTS.mdrebase-stack/commands/push.mdrebase-stack/README.mdrebase-stack/skills/push.mdrebase-stack/skills/continue.mdrebase-stack/skills/start.md
**/guidelines.md
⚙️ CodeRabbit configuration file
**/guidelines.md: Guidelines review (ai-workflows conventions):
- Must contain: Principles, Hard Limits, Safety, Quality, and
Escalation sections (or equivalent coverage)- Content must NOT duplicate SKILL.md or controller.md — each
file has a distinct role- Escalation criteria must be specific and actionable (not vague
"when things go wrong")- Hard limits must be concrete prohibitions, not suggestions
- All phase references should use consistent naming matching
the workflow's actual phase names
Files:
rebase-stack/guidelines.md
**/skills/*.md
📄 CodeRabbit inference engine (Custom checks)
For any changed skills/*.md file, verify that main steps are numbered sequentially (Step 1, Step 2, Step 3... or ## Step 1, ## Step 2...). Flag: gaps in numbering (1, 2, 4), duplicate numbers (two Step 3s), and any skill with more than 10 main steps (cognitive load risk for AI agents). Sub-steps (Step 1a, Step 3b) are acceptable ONLY when they represent conditional branches off the parent step (e.g., "Step 1a: If , do X"). Flag sub-steps that are actually new main steps inserted to avoid renumbering — those should be promoted to full steps with the sequence renumbered.
Files:
rebase-stack/skills/validate.mdrebase-stack/skills/controller.mdrebase-stack/skills/push.mdrebase-stack/skills/continue.mdrebase-stack/skills/start.md
⚙️ CodeRabbit configuration file
**/skills/*.md: Phase skill review (ai-workflows conventions):
- Maximum 10 steps per skill invocation — flag if exceeded
(cognitive load / context window risk for AI agents)- Main steps must be numbered sequentially: no gaps, no
duplicates. Sub-steps (e.g., Step 1a) are allowed ONLY for
conditional branches off a parent step — never as a way to
insert a new main step without renumbering- Internal cross-references (e.g., "see Step 4") must point to
correct step numbers- No step should depend on output from a later step
- Synthesis tasks (summarization, assessment, verdict) must NOT
be buried after heavy per-item processing — they degrade in
long contexts- controller.md must reference sibling skills as phase-name.md
(not skills/phase-name.md) — relative to its own directory- Skills referencing _shared/ resources must use the correct
relative path depth (e.g., ../../_shared/recipes/self-review-gate.md
from skills/)- Failure modes must be documented: what to do when prerequisites
are missing, when zero results are returned, when tools are
unavailable- Escalation criteria must be clear: when to stop and ask the user
- Instructions must be unambiguous — an AI agent reading
top-to-bottom should produce correct output on the first try- If the file has YAML frontmatter, name and description are required
Files:
rebase-stack/skills/validate.mdrebase-stack/skills/controller.mdrebase-stack/skills/push.mdrebase-stack/skills/continue.mdrebase-stack/skills/start.md
**/commands/*.{md,yaml,yml}
📄 CodeRabbit inference engine (Custom checks)
For any file in a commands/ directory, verify the YAML frontmatter name field uses colon notation matching the pattern {workflow-name}:{phase-name} (e.g., bugfix:assess, design:ingest). The workflow-name must match the parent workflow directory name. Flag any command whose name field is missing, does not contain a colon, or has a prefix that doesn't match its workflow directory.
Files:
rebase-stack/commands/continue.mdrebase-stack/commands/validate.mdrebase-stack/commands/start.mdrebase-stack/commands/push.md
**/commands/*.md
📄 CodeRabbit inference engine (AGENTS.md)
commands/*.mdfiles must reference../skills/controller.md,../SKILL.md, or../skills/phase-name.mdas appropriate.
Files:
rebase-stack/commands/continue.mdrebase-stack/commands/validate.mdrebase-stack/commands/start.mdrebase-stack/commands/push.md
⚙️ CodeRabbit configuration file
**/commands/*.md: Command file review (ai-workflows conventions):
- YAML frontmatter required with name and description fields
- name field must use colon notation: {workflow-name}:{phase-name}
(e.g., bugfix:assess, design:ingest)- Commands must be thin wrappers — they dispatch to a skill,
not implement logic themselves. Flag commands that contain
step-by-step instructions or decision logic- Must include $ARGUMENTS placeholder to pass user context
- Path references must be relative to the command file's location:
use ../skills/controller.md or ../SKILL.md, not absolute paths
and not skills/controller.md (missing ../ prefix)- Every command must have a corresponding skill file it routes to
- No IDE-specific syntax
Files:
rebase-stack/commands/continue.mdrebase-stack/commands/validate.mdrebase-stack/commands/start.mdrebase-stack/commands/push.md
**/skills/controller.md
📄 CodeRabbit inference engine (AGENTS.md)
**/skills/controller.md:skills/controller.mdmust reference sibling phase files asphase-name.md, notskills/phase-name.md.
The controller must check for a project-level phase override at.workflows/{workflow}/skills/{phase}.mdbefore falling back to the built-in default.
Files:
rebase-stack/skills/controller.md
**/SKILL.md
📄 CodeRabbit inference engine (Custom checks)
For any SKILL.md file changed in this PR, verify it is under 30 lines total (including frontmatter). SKILL.md must be thin entry points using progressive disclosure. If a SKILL.md exceeds 30 lines, flag it with the count and suggest moving content to guidelines.md or skills/ files.
**/SKILL.md: Each workflow directory must include aSKILL.mdentry point so the installer can auto-discover the workflow.
KeepSKILL.mdthin by staying under 30 lines and pushing details intoguidelines.mdandskills/.
When modifying workflow behavior files, bump the workflow version inSKILL.mdfrontmatter following semver (PATCH, MINOR, or MAJOR as appropriate).
SKILL.mdshould referenceguidelines.mdand, when present,skills/controller.mdusing relative paths.
Files:
rebase-stack/SKILL.md
⚙️ CodeRabbit configuration file
**/SKILL.md: SKILL.md review (ai-workflows conventions):
- YAML frontmatter required: opening/closing --- delimiters
- Required fields: name (lowercase, hyphens only, max 64 chars),
description (third person, includes trigger terms and
activated-by commands)- Total file length must be under 30 lines (progressive
disclosure rule — details belong in guidelines.md or skills/)- Must reference guidelines.md for principles/limits/safety/quality
- Must NOT duplicate content from guidelines.md or controller.md
- Should list all phases with references to skills/ or commands/
- No IDE-specific syntax — plain markdown only
- Verify every file path reference resolves to an existing file
Files:
rebase-stack/SKILL.md
*/README.md
⚙️ CodeRabbit configuration file
*/README.md: Workflow README review (ai-workflows conventions):
- Must document .artifacts/ output path for the workflow
- Phase descriptions must match what SKILL.md and skills/
actually implement — flag any documentation drift- Features mentioned in README must exist in the skill files;
features implemented in skills must be documented in README- Prerequisites (required tools, environment, integrations)
must be listed- Usage examples should show actual command invocations
(e.g., /workflow:phase)
Files:
rebase-stack/README.md
🧠 Learnings (5)
📚 Learning: 2026-04-12T00:25:51.234Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/respond.md:29-31
Timestamp: 2026-04-12T00:25:51.234Z
Learning: In flightctl/ai-workflows skill markdown files, treat path references as two categories:
1) For cross-document markdown links (e.g., links to other .md files like ../skills/controller.md or ../../templates/design.md), use paths relative to the current markdown file’s location so links work under symlinks.
2) For runtime artifact paths used as prose instructions to the AI agent (e.g., .artifacts/design/{issue-number}/publish-metadata.json or .artifacts/prd/config.json), keep them repo-root-relative (start with .artifacts/). Do not convert these artifact paths to be relative to the skill file directory (e.g., don’t rewrite to ../../.artifacts/...), because the AI resolves them from the repo root.
Applied to files:
rebase-stack/skills/validate.mdrebase-stack/skills/controller.mdrebase-stack/skills/push.mdrebase-stack/skills/continue.mdrebase-stack/skills/start.md
📚 Learning: 2026-04-15T10:19:54.839Z
Learnt from: galel12
Repo: flightctl/ai-workflows PR: 22
File: kcs/skills/gather.md:25-26
Timestamp: 2026-04-15T10:19:54.839Z
Learning: In flightctl/ai-workflows, for Jira URL examples inside skill Markdown files, follow the repo-wide convention and use a real example Jira link of the form `https://issues.redhat.com/browse/PROJ-123` (not a generic placeholder like `https://example.com/...`). Since this is a documented convention, do not flag it as a portability/documentation hardcoding issue when reviewing similar skill markdown files.
Applied to files:
rebase-stack/skills/validate.mdrebase-stack/skills/controller.mdrebase-stack/skills/push.mdrebase-stack/skills/continue.mdrebase-stack/skills/start.md
📚 Learning: 2026-04-16T10:39:50.418Z
Learnt from: galel12
Repo: flightctl/ai-workflows PR: 22
File: kcs/skills/gather.md:34-37
Timestamp: 2026-04-16T10:39:50.418Z
Learning: In flightctl/ai-workflows workflow skill files (e.g., kcs/bugfix/prd/design skills), do not require sanitization/normalization of free-form user-supplied identifier placeholders (such as {issue-key} or {issue-number}) when they’re used to construct artifact paths like `.artifacts/{workflow}/{identifier}/`. This is intentional because these workflows run in human-supervised IDE sessions where the user provides the values interactively and confirms the output. Therefore, do not flag missing sanitization/normalization of these identifiers as a security or correctness issue during review for these skill files.
Applied to files:
rebase-stack/skills/validate.mdrebase-stack/skills/controller.mdrebase-stack/skills/push.mdrebase-stack/skills/continue.mdrebase-stack/skills/start.md
📚 Learning: 2026-05-25T17:11:32.207Z
Learnt from: galel12
Repo: flightctl/ai-workflows PR: 47
File: README.md:140-142
Timestamp: 2026-05-25T17:11:32.207Z
Learning: In markdown files under the repo’s skill/command areas (e.g., `skills/**` and `commands/**`), any references to other files on disk (like links/includes pointing to other skill/command markdown such as `../skills/controller.md` or `commands/*.md`) must use relative paths—never absolute paths (no leading `/` or fully-qualified filesystem paths). This ensures the references remain symlink-safe and resolve correctly at runtime. Do not apply this rule to human-facing prose docs like `README.md`/`CONTRIBUTING.md`; when those documents intentionally distinguish user-level vs project-level install locations, keep the absolute user-level paths (e.g., `~/.cursor/commands/`) as written so the distinction is clear.
Applied to files:
rebase-stack/skills/validate.mdrebase-stack/commands/continue.mdrebase-stack/commands/validate.mdrebase-stack/skills/controller.mdrebase-stack/commands/start.mdrebase-stack/commands/push.mdrebase-stack/skills/push.mdrebase-stack/skills/continue.mdrebase-stack/skills/start.md
📚 Learning: 2026-06-15T15:50:50.503Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 64
File: skill-reviewer/SKILL.md:3-3
Timestamp: 2026-06-15T15:50:50.503Z
Learning: In flightctl/ai-workflows, treat `SKILL.md` as a size-constrained document: keep it at or under 30 lines. If a `SKILL.md` already exceeds 30 lines but was not changed by the current PR (a known pre-existing issue), don’t require fixing it as part of the PR. If the PR does modify a too-long `SKILL.md`, refactor it into a thin entry point (e.g., move bulk content to smaller companion docs and leave only a brief overview/links) so the `SKILL.md` itself stays within the 30-line limit.
Applied to files:
rebase-stack/SKILL.md
🪛 LanguageTool
rebase-stack/guidelines.md
[typographical] ~20-~20: In American English, use a period after an abbreviation.
Context: ...gy:** When the conflict is "old version vs evolved version" (a lower branch was ...
(MISSING_PERIOD_AFTER_ABBREVIATION)
rebase-stack/skills/validate.md
[style] ~125-~125: Consider using a more formal/concise alternative here.
Context: ...git worktree add fails for any reason other than "already checked out in the main work...
(OTHER_THAN)
rebase-stack/SKILL.md
[style] ~18-~18: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...commands/continue.mdand follow it. 3. If the user invoked/validate, read com...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~19-~19: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...commands/validate.mdand follow it. 4. If the user invoked/push, read command...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
rebase-stack/README.md
[locale-violation] ~5-~5: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ...dated branches. Creates any missing PRs afterwards, with fork-aware targeting. ## Phase F...
(AFTERWARDS_US)
[uncategorized] ~24-~24: The official name of this software platform is spelled with a capital “H”.
Context: ... PR creation | | gh-stack extension | gh extension install github/gh-stack | | Remote access (origin) ...
(GITHUB)
[typographical] ~83-~83: In American English, use a period after an abbreviation.
Context: ... 2. Resolve conflicts. For "old version vs evolved version" conflicts (the lower ...
(MISSING_PERIOD_AFTER_ABBREVIATION)
rebase-stack/skills/continue.md
[typographical] ~49-~49: In American English, use a period after an abbreviation.
Context: ...iles where the conflict is "old version vs evolved version" (this branch carries a...
(MISSING_PERIOD_AFTER_ABBREVIATION)
rebase-stack/skills/start.md
[typographical] ~115-~115: In American English, use a period after an abbreviation.
Context: ...iles where the conflict is "old version vs evolved version" (this branch carries a...
(MISSING_PERIOD_AFTER_ABBREVIATION)
🔇 Additional comments (11)
AGENTS.md (2)
20-20: LGTM!
150-150: LGTM!README.md (1)
42-44: LGTM!rebase-stack/README.md (1)
1-121: LGTM!rebase-stack/SKILL.md (1)
1-26: LGTM!rebase-stack/commands/start.md (1)
1-12: LGTM!rebase-stack/commands/continue.md (1)
1-12: LGTM!rebase-stack/commands/validate.md (1)
1-12: LGTM!rebase-stack/commands/push.md (1)
1-12: LGTM!rebase-stack/skills/validate.md (1)
1-139: LGTM! The validate skill is well-structured with clear sequential steps, proper cache semantics, good error handling, and correct cross-file contracts with the controller and push skill. The validation range logic correctly handles cumulative branch dependencies, and the worktree setup avoids redundant checkouts.Also applies to: 142-150, 152-160, 164-215
rebase-stack/skills/push.md (1)
1-46: LGTM! The push skill correctly implements atomic push with lease rejection handling, fork-aware PR creation with proper--head owner:branchtargeting, and bottom-to-topDepends on:chaining. Cross-file contracts with the validate skill ({existing-pr},{push-list},{pr-target}) are properly consumed.Also applies to: 54-90
| gh stack rebase --continue --remote origin | ||
| ``` |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Document non-conflict failure mode for gh stack rebase --continue.
If gh stack rebase --continue --remote origin exits non-zero but does not produce a conflict (e.g., no rebase in progress, network failure, or unexpected git state), the skill does not specify what the agent should do. Per path instructions for **/skills/*.md, "Failure modes must be documented: what to do when prerequisites are missing, when zero results are returned, when tools are unavailable." Add an explicit stop-and-report instruction for unexpected non-conflict failures.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@rebase-stack/skills/continue.md` around lines 22 - 23, The `gh stack rebase
--continue` step in `continue.md` only covers the conflict case, but it needs an
explicit non-conflict failure path too. Update the instructions around `gh stack
rebase --continue --remote origin` so that if the command exits non-zero for
reasons like no rebase in progress, network failure, or unexpected git state,
the agent must stop immediately, report the failure, and not attempt further
continuation steps. Keep the guidance tied to the `gh stack rebase --continue`
workflow so the fallback is clear when conflicts are not the cause.
Source: Path instructions
| ```bash | ||
| gh stack submit --auto | ||
| ``` | ||
|
|
||
| - Exit code 0: PRs created and linked as a stack. Done — skip manual creation. | ||
| - Exit code 9: Stacked PRs not enabled. Fall through to manual creation. | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Add explicit stop-and-report for non-9 non-zero exits from gh stack submit --auto.
The instruction only defines behavior for exit code 0 (success) and exit code 9 (Stacked PRs not enabled). If gh stack submit --auto returns any other non-zero exit (e.g., 1 for auth failure, 4 for GitHub API error), the agent has no guidance and may incorrectly fall through to manual PR creation. As per path instructions, escalation criteria must be clear and instructions must be unambiguous so an AI agent produces correct output on the first try.
Add an explicit "any other non-zero exit: stop and report" clause before the manual creation fallback.
🛠️ Proposed fix
- Exit code 0: PRs created and linked as a stack. Done — skip manual creation.
- Exit code 9: Stacked PRs not enabled. Fall through to manual creation.
+ - Any other non-zero exit: stop immediately, report the exit code and full stderr, and do not proceed to manual creation.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```bash | |
| gh stack submit --auto | |
| ``` | |
| - Exit code 0: PRs created and linked as a stack. Done — skip manual creation. | |
| - Exit code 9: Stacked PRs not enabled. Fall through to manual creation. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@rebase-stack/skills/push.md` around lines 47 - 53, The exit handling for gh
stack submit --auto is incomplete because it only covers success and exit code
9, leaving other non-zero failures ambiguous. Update the instructions in push.md
to explicitly state that any non-zero exit other than 9 must stop execution and
report the failure instead of proceeding to manual PR creation. Keep the
behavior tied to gh stack submit --auto so the agent knows only exit code 0
proceeds, 9 falls through, and all other failures are terminal.
Source: Path instructions
| If not found, install it and configure git: | ||
|
|
||
| ```bash | ||
| gh extension install github/gh-stack | ||
| git config rerere.enabled true | ||
| ``` |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Document failure mode for gh extension install failure.
If the gh extension install github/gh-stack command fails (network error, permission denied, GitHub API rate limit, etc.), the skill does not specify what the agent should do. Per path instructions for **/skills/*.md, "Failure modes must be documented: what to do when prerequisites are missing, when zero results are returned, when tools are unavailable." Add an explicit stop-and-report instruction for install failure.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@rebase-stack/skills/start.md` around lines 16 - 21, The installation step for
gh-stack in the skill document lacks a defined failure mode, so update the
instructions around gh extension install github/gh-stack to explicitly say that
if installation fails for any reason, the agent must stop, report the failure,
and not continue with git configuration or later steps. Make sure the guidance
in the relevant skill section clearly names the install command and states the
required action on failure.
Source: Path instructions
| **If exit code 0**: stack already exists. Proceed to Step 4. | ||
|
|
||
| **If exit code 2 ("not in a stack")**: adopt the existing branches. |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Handle unexpected exit codes from gh stack view.
The skill only documents behavior for exit code 0 and exit code 2. Per the path instructions for **/skills/*.md, failure modes must be documented: "what to do when prerequisites are missing, when zero results are returned, when tools are unavailable." For any other non-zero exit code, the agent should stop and report rather than guessing. As per path instructions, escalation criteria must be clear and failure modes documented.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@rebase-stack/skills/start.md` around lines 46 - 48, The `gh stack view` exit
handling in `start.md` only covers exit codes 0 and 2, so add explicit guidance
for any other non-zero exit code. Update the step that branches on `gh stack
view` results to say that unexpected failures should stop the process and be
reported/escalated rather than assuming a stack state. Keep the existing 0/2
behavior for stack already exists and not in a stack, and add a clear fallback
for all other codes.
Source: Path instructions
| Then initialize the stack: | ||
|
|
||
| ```bash | ||
| gh stack init --base {base} \ | ||
| {branch-1} \ | ||
| {branch-2} \ | ||
| ... | ||
| ``` | ||
|
|
||
| `gh stack` will report "Adopted N branches" and detect any existing PRs | ||
| automatically. Verify with: | ||
|
|
||
| ```bash | ||
| gh stack view --json | ||
| ``` |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Document failure mode for gh stack init failure.
If gh stack init fails (e.g., branch does not exist, branch names are wrong, base branch missing), the skill does not tell the agent how to escalate. Per path instructions for **/skills/*.md, failure modes must be documented. Add an explicit stop-and-report instruction for init failure.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@rebase-stack/skills/start.md` around lines 65 - 79, The gh stack init section
in the start.md skill is missing a failure-mode instruction for stack
initialization. Update the instructions around gh stack init and gh stack view
so that if gh stack init fails for any reason (missing base, bad branch names,
nonexistent branches), the agent must stop immediately and report the failure
instead of continuing; keep the guidance tied to the gh stack init workflow so
it’s easy to find even if the surrounding text moves.
Source: Path instructions
| For files with genuinely new code on both sides, show the conflict markers and | ||
| ask the user which version to keep before proceeding. | ||
|
|
||
| Once all files are resolved and staged, run `/continue` automatically. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Inconsistent continue command between start and continue skills.
The agent-fix conflict path in start.md says "run /continue automatically" while the identical path in continue.md (line 61) says "run gh stack rebase --continue --remote origin automatically." These should match: both should use the direct git command (since the agent is fixing), or both should reference the workflow command. As written, an agent reading start.md will emit a different command than one reading continue.md for the same operation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@rebase-stack/skills/start.md` at line 127, The agent-fix path in start.md is
inconsistent with the matching path in continue.md, so align the instruction
text used by the skill docs. Update the guidance around the “all files are
resolved and staged” flow in start.md to match the continue.md wording for the
same operation, using the same command reference consistently in both places.
|
Three of the CodeRabbit findings are worth addressing:
The rest of the CodeRabbit comments (failure mode documentation for individual commands, guidelines.md structure) are covered by the controller's existing "stop and report on any unexpected state" rule — no action needed on those. |
asafbennatan
force-pushed
the
refresh-stack-workflow
branch
from
b6a731b to
7f5aa8e
Compare
Introduces the rebase-stack AI workflow: a multi-phase playbook (/start, /continue, /validate, /push) for rebasing stacked branches via gh-stack. The validate phase checks each branch independently using git worktrees before pushing, catching silent breakage that a clean rebase alone would miss. Key features: - gh stack rebase --remote origin for cascading rebase with conflict guidance - --ours heuristic documented for stale-copy conflicts in stacked rebases - Per-branch lint/test validation using git worktrees (no branch switching) - Validation cache with SHA verification to skip already-passing branches - Atomic push via gh stack push --force-with-lease --atomic - Fork-aware PR creation: gh stack submit --auto with fallback to gh pr create using --head owner:branch --repo upstream for fork topologies - Private preview note for gh-stack Stacked PRs feature Made-with: Cursor
asafbennatan
force-pushed
the
refresh-stack-workflow
branch
from
7f5aa8e to
5f0d076
Compare
2 participants
adds refresh-stack workflow
waits for #65
Updated the rebase-stack workflow documentation and the top-level AI workflow index to add a new stacked-branch rebase flow.
Affected areas:
rebase-stack/: added the full workflow docs, controller, guidelines, and per-command/per-step skill files forstart,continue,validate, andpush.README.md: added the new workflow entry under AI Workflows.AGENTS.md: added the workflow to the current workflows list and file tree.Behavioral/structural changes:
start → validate → push, with/continuefor conflict recovery.guidelines.md, including when to stop, how to resolve conflicts, and how to proceed after validation.Shared conventions:
guidelines.md._shared/resources.