Add within-phase checkpoints to attended bugfix workflow - #98
Conversation
Address user feedback about the bugfix workflow racing forward, making broad assumptions, and suffering from compounding misunderstandings across phases. Adds mid-phase checkpoints in assess (after error signature extraction), diagnose (after hypothesis formation), and fix (after reviewing fix strategy) that pause for user confirmation before proceeding to the expensive/irreversible part of each phase. User redirects are evaluated against evidence rather than taken blindly. Unattended mode explicitly skips these checkpoints. Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>
WalkthroughThe bugfix workflow adds confirmation checkpoints before source exploration, hypothesis testing, and implementation. Unattended execution bypasses these checkpoints. The skill version increases to ChangesBugfix confirmation flow
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 12✅ Passed checks (12 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 `@bugfix/skills/assess.md`:
- Around line 102-106: Update the attended checkpoint templates to explicitly
separate confirmed evidence, assumptions, and unknowns: in
bugfix/skills/assess.md lines 102-106 add all three to the understanding
summary; in bugfix/skills/diagnose.md lines 53-59 label them before hypothesis
testing; and in bugfix/skills/fix.md lines 34-38 include evidence, assumptions,
and implementation risks in the plan.
In `@bugfix/skills/unattended.md`:
- Around line 85-86: Update the unattended execution override in the surrounding
phase-skill instructions to match all confirmation checkpoints, including every
heading beginning with “Checkpoint: Confirm” such as Confirm Understanding,
Confirm Direction, and Confirm Approach. Ensure unattended agents skip these
checkpoints and do not pause for human input.
🪄 Autofix
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: 7dd302e2-1c4f-4c0a-9e50-15bb496f478f
📒 Files selected for processing (5)
bugfix/SKILL.mdbugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.mdbugfix/skills/unattended.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (9)
**/{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:
bugfix/SKILL.mdbugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.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:
bugfix/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).
Files:
bugfix/SKILL.mdbugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.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:
bugfix/SKILL.mdbugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.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: Every workflow must have aSKILL.mdentry point with YAML frontmatter containingname,version, anddescription.
KeepSKILL.mdunder 30 lines and place detailed behavior inguidelines.mdandskills/.
SKILL.mdmay referenceguidelines.mdand optionallyskills/controller.mdusing same-directory relative paths.
Workflows must not auto-advance in attended mode unless an explicit unattended mode is documented.
When behavioral workflow files change, update the corresponding workflow version inSKILL.mdaccording to semver: patch for wording or formatting, minor for behavioral or phase changes, and major for removed, renamed, or restructured phases.
Do not bump versions for non-behavioral files such asREADME.mdandGUIDE.md.
Files:
bugfix/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:
bugfix/SKILL.md
**/*.{md,py,sh}
📄 CodeRabbit inference engine (AGENTS.md)
Workflow content must use plain markdown and contain no IDE-specific syntax.
Files:
bugfix/SKILL.mdbugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.md
**/*
📄 CodeRabbit inference engine (AGENTS.md)
Save all significant workflow outputs under
.artifacts/{workflow-name}/{context}/.
Files:
bugfix/SKILL.mdbugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.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.
When workflows invoke commands that can affect shared systems, follow the documented approval and safety gates: verify
git statusbefore destructive Git operations, confirm branch and base before PR/MR pushes, require explicit approval for Jira writes, and run Vale before applying documentation changes.
Files:
bugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.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:
bugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.md
**/{SKILL,guidelines,README,skills,commands,templates,prompts}/*
📄 CodeRabbit inference engine (AGENTS.md)
Use relative paths for all file references to preserve symlink compatibility across installation scopes.
Files:
bugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.md
**/{SKILL,guidelines,skills,commands,templates,prompts}/*
📄 CodeRabbit inference engine (AGENTS.md)
Behavioral changes must include the version bump in the same commit; do not create a separate version-bump commit.
Files:
bugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.md
🧠 Learnings (8)
📚 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:
bugfix/SKILL.md
📚 Learning: 2026-07-23T14:18:59.204Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 84
File: bugfix/SKILL.md:3-3
Timestamp: 2026-07-23T14:18:59.204Z
Learning: In flightctl/ai-workflows documentation, treat backtick-quoted workflow path templates that include placeholders (e.g., `commands/{command}.md`, `skills/{phase}.md`) as runtime-dispatch/template instructions for AI agents, not literal Markdown links. When these appear, do not flag them as dangling/invalid references solely because the braces indicate substitution of an invoked command or phase name at runtime.
Applied to files:
bugfix/SKILL.mdbugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.md
📚 Learning: 2026-04-10T20:54:40.086Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/revise.md:139-146
Timestamp: 2026-04-10T20:54:40.086Z
Learning: For instructional/procedural Markdown “skill” files under `{design,bugfix}/skills/` (e.g., step-by-step “If X, do Y” content), ignore LanguageTool findings for the specific rule `ENGLISH_WORD_REPEAT_BEGINNING_RULE`. These sequential “If X, do Y” conditional steps are expected for instructional clarity; rewording to satisfy the rule can introduce ambiguity and reduce readability.
Applied to files:
bugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.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:
bugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.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:
bugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.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:
bugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.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:
bugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.md
📚 Learning: 2026-07-22T14:00:30.934Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 77
File: bugfix/skills/feedback-submit.md:80-82
Timestamp: 2026-07-22T14:00:30.934Z
Learning: In flightctl/ai-workflows, the “no-auto-advance” rule should only be enforced for transitions between separately invoked workflow phases (e.g., auto-running “/test” immediately after “/fix” should require an additional user-confirmation checkpoint). Within a single explicitly invoked phase, sequential steps may proceed without an extra checkpoint—e.g., for bugfix skills docs like bugfix/skills/feedback-submit.md and bugfix/skills/pr.md progressing from self-review to staging/commit.
Applied to files:
bugfix/skills/fix.mdbugfix/skills/unattended.mdbugfix/skills/diagnose.mdbugfix/skills/assess.md
🪛 LanguageTool
bugfix/skills/fix.md
[style] ~31-~31: The serial comma (Oxford comma, Harvard comma) is missing.
Context: ... creating a branch or writing any code, pause and present to the user: - The fix approac...
(SERIAL_COMMA_ON)
🔇 Additional comments (1)
bugfix/SKILL.md (1)
3-3: 📐 Maintainability & Code QualityNo structural changes required.
bugfix/SKILL.mdis 26 lines, has valid frontmatter, resolves its references, lists all workflow commands, and has no substantial duplication withguidelines.mdorskills/controller.md.
Each checkpoint now explicitly labels what is grounded in evidence vs. inferred vs. missing, making it easier for the user to spot incorrect assumptions before the AI proceeds. Addresses CodeRabbit review feedback on PR #98. Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@bugfix/skills/fix.md`:
- Around line 37-39: Update the implementation checkpoint in fix.md to require
separate Evidence and Unknowns sections alongside the existing assumptions and
risks prompts. Ensure the checkpoint distinguishes diagnosis-supported facts
from information that remains unverified before branch creation or code changes.
🪄 Autofix
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: f495a104-bd0d-49fb-b02b-998d9af7ba1b
📒 Files selected for processing (3)
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.md
📜 Review details
⏰ Context from checks skipped due to timeout. (1)
- GitHub Check: Analyze (python)
🧰 Additional context used
📓 Path-based instructions (7)
**/{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:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.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:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.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:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.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.
When workflows invoke commands that can affect shared systems, follow the documented approval and safety gates: verify
git statusbefore destructive Git operations, confirm branch and base before PR/MR pushes, require explicit approval for Jira writes, and run Vale before applying documentation changes.
Files:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.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:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.md
**/*.{md,py,sh}
📄 CodeRabbit inference engine (AGENTS.md)
Workflow content must use plain markdown and contain no IDE-specific syntax.
Files:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.md
**/{SKILL,guidelines,README,skills,commands,templates,prompts}/*
📄 CodeRabbit inference engine (AGENTS.md)
Use relative paths for all file references to preserve symlink compatibility across installation scopes.
Files:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.md
**/*
📄 CodeRabbit inference engine (AGENTS.md)
Save all significant workflow outputs under
.artifacts/{workflow-name}/{context}/.
Files:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.md
**/{SKILL,guidelines,skills,commands,templates,prompts}/*
📄 CodeRabbit inference engine (AGENTS.md)
Behavioral changes must include the version bump in the same commit; do not create a separate version-bump commit.
Files:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.md
🧠 Learnings (7)
📚 Learning: 2026-04-10T20:54:40.086Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/revise.md:139-146
Timestamp: 2026-04-10T20:54:40.086Z
Learning: For instructional/procedural Markdown “skill” files under `{design,bugfix}/skills/` (e.g., step-by-step “If X, do Y” content), ignore LanguageTool findings for the specific rule `ENGLISH_WORD_REPEAT_BEGINNING_RULE`. These sequential “If X, do Y” conditional steps are expected for instructional clarity; rewording to satisfy the rule can introduce ambiguity and reduce readability.
Applied to files:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.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:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.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:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.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:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.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:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.md
📚 Learning: 2026-07-22T14:00:30.934Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 77
File: bugfix/skills/feedback-submit.md:80-82
Timestamp: 2026-07-22T14:00:30.934Z
Learning: In flightctl/ai-workflows, the “no-auto-advance” rule should only be enforced for transitions between separately invoked workflow phases (e.g., auto-running “/test” immediately after “/fix” should require an additional user-confirmation checkpoint). Within a single explicitly invoked phase, sequential steps may proceed without an extra checkpoint—e.g., for bugfix skills docs like bugfix/skills/feedback-submit.md and bugfix/skills/pr.md progressing from self-review to staging/commit.
Applied to files:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.md
📚 Learning: 2026-07-23T14:18:59.204Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 84
File: bugfix/SKILL.md:3-3
Timestamp: 2026-07-23T14:18:59.204Z
Learning: In flightctl/ai-workflows documentation, treat backtick-quoted workflow path templates that include placeholders (e.g., `commands/{command}.md`, `skills/{phase}.md`) as runtime-dispatch/template instructions for AI agents, not literal Markdown links. When these appear, do not flag them as dangling/invalid references solely because the braces indicate substitution of an invoked command or phase name at runtime.
Applied to files:
bugfix/skills/assess.mdbugfix/skills/diagnose.mdbugfix/skills/fix.md
🔇 Additional comments (2)
bugfix/skills/assess.md (1)
102-107: LGTM!bugfix/skills/diagnose.md (1)
56-59: LGTM!
The fix checkpoint now uses the same four-part structure (Evidence, Assumptions, Unknowns, Risks) as the assess and diagnose checkpoints, so users see a consistent format across all three pause points. Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@bugfix/skills/fix.md`:
- Around line 37-43: Update the prerequisite flow in the bugfix skill to verify
that .artifacts/bugfix/{issue}/root-cause.md exists and provides diagnosis
evidence before proceeding to branch creation or implementation. If the analysis
is missing or insufficient, stop and direct the agent to run /diagnose or obtain
explicit verification; do not allow unsupported evidence or a fallback to
continue the workflow.
🪄 Autofix
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: 143339a9-8f01-48b1-b17c-18ef612b7cdf
📒 Files selected for processing (1)
bugfix/skills/fix.md
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
- GitHub Check: Analyze (actions)
- GitHub Check: Analyze (python)
🧰 Additional context used
📓 Path-based instructions (7)
**/{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:
bugfix/skills/fix.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:
bugfix/skills/fix.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:
bugfix/skills/fix.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.
When workflows invoke commands that can affect shared systems, follow the documented approval and safety gates: verify
git statusbefore destructive Git operations, confirm branch and base before PR/MR pushes, require explicit approval for Jira writes, and run Vale before applying documentation changes.
Files:
bugfix/skills/fix.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:
bugfix/skills/fix.md
**/*.{md,py,sh}
📄 CodeRabbit inference engine (AGENTS.md)
Workflow content must use plain markdown and contain no IDE-specific syntax.
Files:
bugfix/skills/fix.md
**/{SKILL,guidelines,README,skills,commands,templates,prompts}/*
📄 CodeRabbit inference engine (AGENTS.md)
Use relative paths for all file references to preserve symlink compatibility across installation scopes.
Files:
bugfix/skills/fix.md
**/*
📄 CodeRabbit inference engine (AGENTS.md)
Save all significant workflow outputs under
.artifacts/{workflow-name}/{context}/.
Files:
bugfix/skills/fix.md
**/{SKILL,guidelines,skills,commands,templates,prompts}/*
📄 CodeRabbit inference engine (AGENTS.md)
Behavioral changes must include the version bump in the same commit; do not create a separate version-bump commit.
Files:
bugfix/skills/fix.md
🧠 Learnings (7)
📚 Learning: 2026-04-10T20:54:40.086Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/revise.md:139-146
Timestamp: 2026-04-10T20:54:40.086Z
Learning: For instructional/procedural Markdown “skill” files under `{design,bugfix}/skills/` (e.g., step-by-step “If X, do Y” content), ignore LanguageTool findings for the specific rule `ENGLISH_WORD_REPEAT_BEGINNING_RULE`. These sequential “If X, do Y” conditional steps are expected for instructional clarity; rewording to satisfy the rule can introduce ambiguity and reduce readability.
Applied to files:
bugfix/skills/fix.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:
bugfix/skills/fix.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:
bugfix/skills/fix.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:
bugfix/skills/fix.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:
bugfix/skills/fix.md
📚 Learning: 2026-07-22T14:00:30.934Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 77
File: bugfix/skills/feedback-submit.md:80-82
Timestamp: 2026-07-22T14:00:30.934Z
Learning: In flightctl/ai-workflows, the “no-auto-advance” rule should only be enforced for transitions between separately invoked workflow phases (e.g., auto-running “/test” immediately after “/fix” should require an additional user-confirmation checkpoint). Within a single explicitly invoked phase, sequential steps may proceed without an extra checkpoint—e.g., for bugfix skills docs like bugfix/skills/feedback-submit.md and bugfix/skills/pr.md progressing from self-review to staging/commit.
Applied to files:
bugfix/skills/fix.md
📚 Learning: 2026-07-23T14:18:59.204Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 84
File: bugfix/SKILL.md:3-3
Timestamp: 2026-07-23T14:18:59.204Z
Learning: In flightctl/ai-workflows documentation, treat backtick-quoted workflow path templates that include placeholders (e.g., `commands/{command}.md`, `skills/{phase}.md`) as runtime-dispatch/template instructions for AI agents, not literal Markdown links. When these appear, do not flag them as dangling/invalid references solely because the braces indicate substitution of an invoked command or phase name at runtime.
Applied to files:
bugfix/skills/fix.md
There was a problem hiding this comment.
Overview
Adds a ### Checkpoint: Confirm ... section to assess.md, diagnose.md, and fix.md, each placed at the "understanding → action" boundary within a phase (before source exploration, before hypothesis testing, before branching/coding respectively). unattended.md's override rule is extended to skip these sections. SKILL.md is bumped 0.5.0 → 0.6.0. This directly targets the stated problem: phases currently run start-to-finish without a mid-phase pause, so a wrong assumption early in a phase snowballs before the user ever gets a chance to redirect.
What's good
- Consistent design across all three checkpoints — same
Evidence / Assumptions / Unknownsframing, same three-way response handling (confirm / evidence-based redirect / bare rejection), same placement rule (right before the expensive/irreversible step). - Version bump is correct per
AGENTS.md's Workflow Versioning rules — adding steps to a behavioral file is a MINOR bump, bundled in the same commit as required. unattended.mdoverride done correctly and narrowly — no other workflow readsbugfix/skills/{assess,diagnose,fix}.mddirectly, so this was the only place needing the override, and it was updated.- The redirect-handling isn't a rubber stamp — "evaluate the redirect against the evidence... if it contradicts, say so" avoids the failure mode where confirmation becomes theater that just does whatever the user says next.
- Checkpoint headers all start with the literal string
"Checkpoint: Confirm", matching exactly what the unattended override searches for — easy to keep in sync if a fourth checkpoint is added later.
Suggestions
- Duplicated "Handling the response" boilerplate (minor). The three-bullet confirm/redirect/reject block is repeated near-verbatim across all three files. This repo has a
_shared/recipes/convention for exactly this kind of reusable procedure. Since the pattern is bugfix-only for now, inlining is defensible, but worth extracting if a second workflow adopts checkpoints later. - README.md not updated (minor, non-blocking). The per-phase descriptions don't mention the new mid-phase pause. Not required by versioning rules, but helps users know what to expect.
- Worth confirming intent:
assess.md's checkpoint fires before any source-code exploration, based only on the raw bug report — for a bug with an exact stack trace and file:line, there's little to actually redirect on. Product tradeoff, not a bug — just worth confirming the pause is meant to be unconditional rather than confidence-gated.
Risks
None structural. The change is confined to prompt/instruction text, the override path was verified as the only consumer needing updates, and the manual test plan in the PR description is appropriate for this artifact type.
No correctness issues found — ready to merge modulo the two minor doc/dedup suggestions above.
2 participants
Summary
Motivation
User feedback identified three problems with the attended bugfix workflow:
Design
Each checkpoint is placed at the boundary between "understanding" and "action" within a phase:
/assess/diagnose/fixUser redirects are evaluated against evidence — the AI pushes back if a redirect contradicts what the code shows, rather than blindly complying. Bare "no" responses prompt a targeted follow-up question.
Test plan
/assesson a Jira bug — verify it pauses after error signature extraction and presents understanding before exploring code/diagnose— verify it pauses after hypothesis formation/fix— verify it pauses after reviewing fix strategy/bugfix:unattended— verify checkpoints are skipped and the workflow runs end-to-end without pausingAssisted-by: Claude Opus 4.6 (1M) noreply@anthropic.com
Summary
/assess,/diagnose, and/fixworkflows./unattendedto ignoreCheckpoint: Confirminstructions.0.5.0to0.6.0._shared/resources or cross-workflow conventions.