Repository navigation
Refresh stack workflow - #66
Conversation
|
Warning Review limit reached
Next review available in: 55 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)
WalkthroughAdds a new Changesrebase-stack workflow introduction
Estimated code review effort: 3 (Moderate) | ~25 minutes Suggested labels: Suggested reviewers: Important Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (1 error, 1 warning, 1 inconclusive)
✅ 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 |
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
|
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. |
5f0d076 to
31f3940
Compare
fixed |
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
rebase-stack/skills/push.md (1)
51-52: 🎯 Functional Correctness | 🔴 Critical | ⚡ Quick winOnly exit code 9 should fall through to manual PR creation.
The current instruction sends every non-zero exit from
gh stack submit --autoto manual PR creation, including auth failures, API errors, and lock timeouts. This contradicts the README contract (which specifically calls out exit code 9) and the previous review fix request. Only exit code 9 means "Stacked PRs not enabled"; all other non-zero exits must stop and report.- Exit code 0: PRs created and linked as a stack. Done — skip manual creation. - - Any non-zero exit (including exit code 9): fall through to 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.🤖 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 51 - 52, The `gh stack submit --auto` exit handling in `push.md` is too broad: only exit code 9 should fall through to manual PR creation. Update the guidance around the `gh stack submit --auto` flow so that exit code 0 skips manual creation, exit code 9 triggers manual creation, and every other non-zero exit is treated as a hard failure that reports and stops instead of continuing.
🤖 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/commands/continue.md`:
- Around line 2-3: The command metadata description for rebase-stack:continue is
inconsistent with the documented behavior in the README. Update the description
in the continue command definition so it matches the /continue contract used by
the rebase-stack flow and clearly states that it resumes the rebase locally
after conflict resolution without pushing or force-pushing branches. Refer to
the rebase-stack:continue command entry and keep the wording aligned with the
documented local-only behavior.
In `@rebase-stack/guidelines.md`:
- Line 16: Update the validation guideline in guidelines.md to distinguish
improper skipping from cache-based reuse: reference the validation cache
behavior in validate.md Step 4 and clarify that validation should not be skipped
when branches changed, but may be omitted when the branch SHA matches the cached
validated SHA. Keep the wording aligned with the existing validation policy so
the rule allows legitimate cache hits while still requiring validation for
changed branches.
---
Duplicate comments:
In `@rebase-stack/skills/push.md`:
- Around line 51-52: The `gh stack submit --auto` exit handling in `push.md` is
too broad: only exit code 9 should fall through to manual PR creation. Update
the guidance around the `gh stack submit --auto` flow so that exit code 0 skips
manual creation, exit code 9 triggers manual creation, and every other non-zero
exit is treated as a hard failure that reports and stops instead of continuing.
🪄 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: 533adfe0-419f-46d0-904c-5de95a791cc4
📒 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 (16)
**/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/validate.mdrebase-stack/commands/push.mdrebase-stack/commands/start.mdrebase-stack/commands/continue.md
**/{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/commands/validate.mdrebase-stack/commands/push.mdrebase-stack/commands/start.mdrebase-stack/guidelines.mdrebase-stack/commands/continue.mdrebase-stack/SKILL.mdrebase-stack/skills/controller.mdrebase-stack/skills/validate.mdrebase-stack/skills/continue.mdrebase-stack/skills/push.mdrebase-stack/skills/start.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).
Files:
rebase-stack/commands/validate.mdrebase-stack/commands/push.mdrebase-stack/commands/start.mdrebase-stack/guidelines.mdrebase-stack/commands/continue.mdrebase-stack/SKILL.mdrebase-stack/skills/controller.mdrebase-stack/README.mdREADME.mdrebase-stack/skills/validate.mdAGENTS.mdrebase-stack/skills/continue.mdrebase-stack/skills/push.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/commands/validate.mdrebase-stack/commands/push.mdrebase-stack/commands/start.mdrebase-stack/guidelines.mdrebase-stack/commands/continue.mdrebase-stack/SKILL.mdrebase-stack/skills/controller.mdrebase-stack/README.mdREADME.mdrebase-stack/skills/validate.mdAGENTS.mdrebase-stack/skills/continue.mdrebase-stack/skills/push.mdrebase-stack/skills/start.md
*/commands/*.md
📄 CodeRabbit inference engine (AGENTS.md)
Use
commands/*.mdas thin wrappers that invoke../skills/controller.md,../SKILL.md, or../skills/phase-name.mdas appropriate.
Files:
rebase-stack/commands/validate.mdrebase-stack/commands/push.mdrebase-stack/commands/start.mdrebase-stack/commands/continue.md
**/{SKILL.md,guidelines.md,skills/*.md,commands/*.md,templates/*,prompts/*,scripts/*,_shared/**/*.md}
📄 CodeRabbit inference engine (AGENTS.md)
Behavioral files that require version bumps include
SKILL.mdbody,guidelines.md,skills/*.md,commands/*.md,templates/*,prompts/*,scripts/*,_shared/**/*.md, and root-level markdown files in workflow directories that are read during execution.
Files:
rebase-stack/commands/validate.mdrebase-stack/commands/push.mdrebase-stack/commands/start.mdrebase-stack/guidelines.mdrebase-stack/commands/continue.mdrebase-stack/SKILL.mdrebase-stack/skills/controller.mdrebase-stack/skills/validate.mdrebase-stack/skills/continue.mdrebase-stack/skills/push.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/commands/validate.mdrebase-stack/commands/push.mdrebase-stack/commands/start.mdrebase-stack/guidelines.mdrebase-stack/commands/continue.mdrebase-stack/SKILL.mdrebase-stack/skills/controller.mdrebase-stack/README.mdREADME.mdrebase-stack/skills/validate.mdAGENTS.mdrebase-stack/skills/continue.mdrebase-stack/skills/push.mdrebase-stack/skills/start.md
**/commands/*.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/validate.mdrebase-stack/commands/push.mdrebase-stack/commands/start.mdrebase-stack/commands/continue.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/SKILL.mdrebase-stack/skills/controller.md
*/guidelines.md
📄 CodeRabbit inference engine (AGENTS.md)
Put behavioral rules, hard limits, safety constraints, and quality guidance in
guidelines.md.
Files:
rebase-stack/guidelines.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
**/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: When modifying a workflow's behavioral files, update the workflow version inSKILL.mdusing semver: PATCH for wording/formatting, MINOR for step/rule/template changes, and MAJOR for removals/renames/restructuring.
Include the version bump in the same commit as the behavioral change.
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
*/SKILL.md
📄 CodeRabbit inference engine (AGENTS.md)
*/SKILL.md: Every workflow directory must contain aSKILL.mdentry point with YAML frontmatter (name,version,description).
KeepSKILL.mdthin: it should be under 30 lines, with most details living inguidelines.mdandskills/.
SKILL.mdshould referenceguidelines.mdand, optionally,skills/controller.mdusing same-directory relative links.
Files:
rebase-stack/SKILL.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/controller.mdrebase-stack/skills/validate.mdrebase-stack/skills/continue.mdrebase-stack/skills/push.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/controller.mdrebase-stack/skills/validate.mdrebase-stack/skills/continue.mdrebase-stack/skills/push.mdrebase-stack/skills/start.md
*/skills/*.md
📄 CodeRabbit inference engine (AGENTS.md)
Use
skills/*.mdfor phase implementations, including optional controller dispatchers and phase files.
Files:
rebase-stack/skills/controller.mdrebase-stack/skills/validate.mdrebase-stack/skills/continue.mdrebase-stack/skills/push.mdrebase-stack/skills/start.md
*/skills/controller.md
📄 CodeRabbit inference engine (AGENTS.md)
When present,
skills/controller.mdshould reference sibling phase files asphase-name.md, notskills/phase-name.md.
Files:
rebase-stack/skills/controller.md
*/README.md
📄 CodeRabbit inference engine (AGENTS.md)
Use
README.mdfor human-readable documentation such as prerequisites, artifacts, and usage.
Files:
rebase-stack/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 (6)
📓 Common learnings
Learnt from: CR
Repo: flightctl/ai-workflows
Timestamp: 2026-07-01T06:12:57.157Z
Learning: Each workflow is a self-contained directory with structured markdown files that AI agents can read and execute.
Learnt from: CR
Repo: flightctl/ai-workflows
Timestamp: 2026-07-01T06:12:57.157Z
Learning: Any directory containing a `SKILL.md` file is automatically discovered by the installer.
Learnt from: CR
Repo: flightctl/ai-workflows
Timestamp: 2026-07-01T06:12:57.157Z
Learning: Prefer progressive disclosure: keep top-level entry files thin and move details into deeper workflow files.
Learnt from: CR
Repo: flightctl/ai-workflows
Timestamp: 2026-07-01T06:12:57.157Z
Learning: All file references must use relative paths only, for symlink compatibility.
Learnt from: CR
Repo: flightctl/ai-workflows
Timestamp: 2026-07-01T06:12:57.157Z
Learning: Most workflows should use phase-based execution with explicit transitions.
Learnt from: CR
Repo: flightctl/ai-workflows
Timestamp: 2026-07-01T06:12:57.157Z
Learning: Cross-cutting shared resources belong in `_shared/` and should be referenced by relative path.
Learnt from: CR
Repo: flightctl/ai-workflows
Timestamp: 2026-07-01T06:12:57.157Z
Learning: Do not use IDE-specific syntax; all workflow content must be plain markdown.
Learnt from: CR
Repo: flightctl/ai-workflows
Timestamp: 2026-07-01T06:12:57.157Z
Learning: Workflows should wait for user input between phases in attended mode unless an explicit unattended mode is documented.
Learnt from: CR
Repo: flightctl/ai-workflows
Timestamp: 2026-07-01T06:12:57.157Z
Learning: All significant outputs must be saved under `.artifacts/{workflow-name}/{context}/`.
Learnt from: CR
Repo: flightctl/ai-workflows
Timestamp: 2026-07-01T06:12:57.157Z
Learning: Workflows may be installed globally or per-project in any supported environment (Cursor, Claude Code, Gemini).
Learnt from: CR
Repo: flightctl/ai-workflows
Timestamp: 2026-07-01T06:12:57.157Z
Learning: When workflows invoke commands affecting shared systems, verify `git status` before destructive git operations, confirm branch and base before PR/MR creation, require explicit approval for Jira writes, and run Vale validation before applying documentation changes.
📚 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/commands/validate.mdrebase-stack/commands/push.mdrebase-stack/commands/start.mdrebase-stack/commands/continue.mdrebase-stack/skills/controller.mdrebase-stack/skills/validate.mdrebase-stack/skills/continue.mdrebase-stack/skills/push.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
📚 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/controller.mdrebase-stack/skills/validate.mdrebase-stack/skills/continue.mdrebase-stack/skills/push.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/controller.mdrebase-stack/skills/validate.mdrebase-stack/skills/continue.mdrebase-stack/skills/push.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/controller.mdrebase-stack/skills/validate.mdrebase-stack/skills/continue.mdrebase-stack/skills/push.mdrebase-stack/skills/start.md
🪛 LanguageTool
rebase-stack/guidelines.md
[style] ~16-~16: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...licit choice (fix-for-me vs. manual). - Never skip the validation phase when branches...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[typographical] ~35-~35: 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/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/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/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] ~127-~127: 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 (15)
rebase-stack/skills/push.md (2)
12-24: LGTM!
26-89: LGTM! (excluding the exit code issue already flagged)rebase-stack/skills/validate.md (1)
1-215: LGTM! (excluding the minor log cleanup comment ambiguity noted above)AGENTS.md (1)
20-20: LGTM!Also applies to: 150-150
README.md (1)
42-44: LGTM!rebase-stack/README.md (2)
117-119: Verifygh stack pushaccepts--force-with-lease --atomic.The README states that
gh stack pushuses--force-with-lease --atomic. Confirm that thepush.mdskill actually passes these flags to the push command, and thatgh stack pushsupports them (as opposed to usinggit pushdirectly). If the skill uses different flags or a different command, align the README.
1-122: LGTM! The README accurately describes the workflow phases, prerequisites, and artifacts. Cross-file consistency with controller.md, start.md, continue.md, validate.md, and push.md is verified.rebase-stack/SKILL.md (1)
1-26: LGTM!rebase-stack/skills/start.md (2)
139-139: Verifygh stack rebase --continueaccepts--remote origin.The skill instructs running
gh stack rebase --continue --remote origin. In standard git,git rebase --continuedoes not accept the same flags as the initialgit rebasecommand. Verify whethergh stack rebase --continueaccepts or requires--remote origin, or if it should begh stack rebase --continuealone. If the flag is rejected, remove it from bothstart.mdandcontinue.md.
1-152: LGTM! Well-structured with clear failure modes, escalation paths, and conflict resolution guidance. Past review issues have been addressed.rebase-stack/skills/continue.md (1)
1-84: LGTM! The continue skill correctly handles conflict resolution loops, unexpected failures, and user hand-off. It mirrors the start.md conflict path consistently. The--remote originflag issue ongh stack rebase --continueis shared withstart.md(see comment there) and should be fixed in both files together.rebase-stack/commands/start.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/controller.md (1)
1-46: LGTM!
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 Co-authored-by: Cursor <cursoragent@cursor.com>
31f3940 to
0419b21
Compare
Refresh stack workflow
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 full workflow documentation, includingguidelines.md, the controller (skills/controller.md), and per-phase command/skill docs forstart,continue,validate, andpush(commands/*.mdandskills/*.md).README.md: added the new Rebase Stack workflow entry under AI Workflows / What's Included, linking torebase-stack/README.md.AGENTS.md: added the workflow to the “Current workflows” list and theai-workflows/file tree.rebase-stack/SKILL.mdas the user-facing skill entrypoint.Behavioral/structural changes:
/start→ (conflicts)/continue→/validate→/push, with/continueand/startdesigned to be local-only (no pushing).guidelines.mdwith explicit operational rules: branch-by-branch validation before pushing, strict stop/report behavior on ambiguous or unexpectedgit/gh stackstate, and detailed conflict-resolution guidance (“old vs evolved” handling via--ours)./start.skills/push.mdnow stops and reports on any unexpected non-zero exit after handling theexit code 9case forgh stack submit --auto.gh stack submit --autowhen stacked PRs are enabled (non-fork path), otherwise fall back to manual PR creation with correct--head/--repowiring.--update-refsto match the actual implementation (gh stack rebase).AGENTS.mdto include the missingvalidatestep.guidelines.md(with attention to symlink compatibility via../guidelines.md)..artifacts/rebase-stack/logs/(instead of/tmp/).Shared conventions:
guidelines.md._shared/were introduced.