Decouple cross-workflow artifact dependencies and publish clarifications - #100
Conversation
Enforce the principle that .artifacts/{workflow-name}/ is each workflow's
private state by eliminating all cross-workflow artifact reads.
- Move config.json from .artifacts/prd/config.json to .artifacts/config.json
(workspace-level config, not owned by any workflow)
- Design workflow reads PRD and clarifications from the docs repo instead
of .artifacts/prd/ — finds PRD by searching for the issue key
- Feature sizing in decompose reads from Jira directly instead of
.artifacts/prd/ or .artifacts/sizing/
- Eliminate design's read of prd's publish-metadata.json — derive
release/feature from the docs repo directory structure
- Publish clarifications.md alongside prd.md in the docs repo so
[Clarify: R1.Q2] tags reference a durable, published artifact
- Restructure clarification log format for human readability: Answer,
Impact, and Decision as separate headings instead of bold-inline;
locked decisions inline with their Q&A entry as #### Decision (D{N})
- Document artifact isolation as constraint #7 in AGENTS.md
Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>
WalkthroughWorkflows now isolate artifacts and share workspace-level documentation repository configuration. PRD publication supports structured clarification records. Design ingestion resolves published PRDs and propagates their paths through later design stages. ChangesWorkflow structure and published inputs
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 11 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (11 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: 9
🤖 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 `@AGENTS.md`:
- Line 88: Align the cross-workflow artifact boundary in AGENTS.md:88 by adding
clarifications.md to the permitted published-docs interfaces or making the
parenthetical list explicitly illustrative. In prd/GUIDE.md:90, remove guidance
allowing downstream workflows to read .artifacts/prd/{issue-key}/ directly and
direct them to the corresponding published docs repository copies instead.
In `@design/SKILL.md`:
- Line 3: Update the command path reference in SKILL.md so it no longer uses the
unresolved commands/{command}.md placeholder; replace it with concrete existing
command file paths or move the placeholder outside the file-path reference.
In `@design/skills/decompose.md`:
- Around line 352-354: Update the Feature sizing step in the Jira lookup
instructions to distinguish a successful read with both Size and Story Points
unset from authentication, network, or lookup failures. Skip the sizing check
only after confirming the Feature issue was retrieved successfully and both
fields are absent; otherwise stop and report the external lookup failure.
Document missing prerequisites and unavailable-tool failure modes as required by
the path instructions.
- Line 37: Reduce the main workflow in the decompose skill from Steps 1–14 to at
most 10 sequentially numbered steps. Move review, re-review, validation, and
reporting into a companion skill or combine related phases, while preserving the
existing PRD path guidance in the PRD step.
In `@design/skills/ingest.md`:
- Around line 70-82: Validate every PRD directory before using it: in
design/skills/ingest.md lines 70-82, require a readable prd.md in each directory
match and restrict any user-provided fallback path to the validated
docs_repo_path; in design/skills/publish.md lines 85-106, require prd.md and the
expected {release}/{feature} directory structure before deriving defaults.
- Around line 64-66: Update the configuration-loading step in the ingest
workflow to validate existing .artifacts/config.json values before use, applying
the checks from publish.md: confirm docs_repo_path exists, is a Git repository,
and has a remote matching docs_repo_remote. If validation fails, stop and ask
the user for corrected path and remote values; preserve the existing
prompt-and-write flow when the configuration is absent.
In `@design/skills/research.md`:
- Around line 69-71: Handle the “None published” sentinel consistently before
consuming clarification artifacts: in design/skills/research.md lines 69-71,
skip the clarification read when the PRD Summary path is “None published,”
otherwise read the recorded path; apply the same sentinel check before loading
locked decisions in design/skills/revise.md lines 40-41 and before validating
locked decisions in design/skills/respond.md lines 133-138. Keep the existing
behavior for actual clarification paths unchanged.
In `@prd/skills/controller.md`:
- Around line 54-55: Align the shared configuration lifecycle across all
affected documentation: in prd/skills/controller.md lines 54-55, state that
eligible /ingest and /publish phases may create .artifacts/config.json while
later phases validate and reuse it; in design/skills/sync.md lines 639-643,
require prompting for or creating missing configuration when publish metadata
and a local testplan exist instead of silently skipping; in prd/skills/revise.md
lines 81-85, apply the same missing-configuration handling and define migration
or compatibility behavior for legacy .artifacts/prd/config.json.
In `@prd/skills/publish.md`:
- Around line 153-162: Update the publication workflow around the
clarification-file copy to run the repository-configured Vale validation against
both 03-prd.md and 02-clarifications.md first; if validation fails, stop before
copying or staging either file. Preserve the existing cp and git add behavior
only after both files pass validation.
🪄 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: a29df7ff-a371-4f25-a700-af2d8c98a5b7
📒 Files selected for processing (23)
AGENTS.mddesign/README.mddesign/SKILL.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/draft.mddesign/skills/ingest.mddesign/skills/publish.mddesign/skills/research.mddesign/skills/respond.mddesign/skills/revise.mddesign/skills/sync.mde2e/SKILL.mde2e/skills/ingest.mdimplement/SKILL.mdimplement/skills/ingest.mdprd/GUIDE.mdprd/SKILL.mdprd/skills/clarify.mdprd/skills/controller.mdprd/skills/publish.mdprd/skills/respond.mdprd/skills/revise.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (8)
**/{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:
design/SKILL.mdprd/SKILL.mdprd/skills/controller.mdprd/skills/revise.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mdimplement/SKILL.mde2e/skills/ingest.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.mdimplement/skills/ingest.mdprd/skills/clarify.mde2e/SKILL.mdprd/skills/publish.mdprd/skills/respond.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:
design/SKILL.mdprd/SKILL.mdprd/skills/controller.mddesign/skills/controller.mdimplement/SKILL.mde2e/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 file references must use relative paths for symlink compatibility.
Workflow content must use plain Markdown and contain no IDE-specific syntax.
Files:
design/SKILL.mdprd/SKILL.mdAGENTS.mdprd/skills/controller.mddesign/README.mdprd/skills/revise.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mdprd/GUIDE.mdimplement/SKILL.mde2e/skills/ingest.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.mdimplement/skills/ingest.mdprd/skills/clarify.mde2e/SKILL.mdprd/skills/publish.mdprd/skills/respond.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:
design/SKILL.mdprd/SKILL.mdAGENTS.mdprd/skills/controller.mddesign/README.mdprd/skills/revise.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mdprd/GUIDE.mdimplement/SKILL.mde2e/skills/ingest.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.mdimplement/skills/ingest.mdprd/skills/clarify.mde2e/SKILL.mdprd/skills/publish.mdprd/skills/respond.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 directory must contain aSKILL.mdentry point with YAML frontmatter; keepSKILL.mdunder 30 lines and referenceguidelines.mdand, when applicable,skills/controller.mdusing relative paths.
When behavioral workflow files change, update the corresponding workflowSKILL.mdversion using semver: PATCH for wording or formatting changes, MINOR for behavioral or phase changes, and MAJOR for removed or renamed phases or commands.
Files:
design/SKILL.mdprd/SKILL.mdimplement/SKILL.mde2e/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:
design/SKILL.mdprd/SKILL.mdimplement/SKILL.mde2e/SKILL.md
**/*
📄 CodeRabbit inference engine (AGENTS.md)
**/*: All significant workflow outputs must be persisted under.artifacts/{workflow-name}/{context}/.
Workflows must isolate artifact state: each workflow may only read from and write to its own.artifacts/{workflow-name}/directory, except for the documented shared interfaces.
Include behavioral-file version bumps in the same commit as the behavioral change; do not create a separate version-bump commit.
Before destructive Git operations, verify the repository state withgit status.
Before creating a PR or MR, confirm the branch and base before pushing.
Onlycve-fix /close,design /sync, andsizing /applymay write to Jira, and each requires explicit approval.
Run Vale validation before applying documentation changes to repository files.
Files:
design/SKILL.mdprd/SKILL.mdAGENTS.mdprd/skills/controller.mddesign/README.mdprd/skills/revise.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mdprd/GUIDE.mdimplement/SKILL.mde2e/skills/ingest.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.mdimplement/skills/ingest.mdprd/skills/clarify.mde2e/SKILL.mdprd/skills/publish.mdprd/skills/respond.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.
Workflows must not auto-advance in attended mode; they must wait for user input between phases unless an explicit unattended mode is documented.
Files:
prd/skills/controller.mdprd/skills/revise.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mde2e/skills/ingest.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.mdimplement/skills/ingest.mdprd/skills/clarify.mdprd/skills/publish.mdprd/skills/respond.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:
prd/skills/controller.mdprd/skills/revise.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mde2e/skills/ingest.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.mdimplement/skills/ingest.mdprd/skills/clarify.mdprd/skills/publish.mdprd/skills/respond.md
**/skills/controller.md
📄 CodeRabbit inference engine (AGENTS.md)
Controllers must reference sibling skills using
phase-name.md, notskills/phase-name.md.
Files:
prd/skills/controller.mddesign/skills/controller.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:
design/README.md
🧠 Learnings (14)
📚 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:
design/SKILL.mdprd/SKILL.mdimplement/SKILL.mde2e/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:
design/SKILL.mdprd/SKILL.mdAGENTS.mdprd/skills/controller.mddesign/README.mdprd/skills/revise.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mdprd/GUIDE.mdimplement/SKILL.mde2e/skills/ingest.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.mdimplement/skills/ingest.mdprd/skills/clarify.mde2e/SKILL.mdprd/skills/publish.mdprd/skills/respond.md
📚 Learning: 2026-08-06T13:07:53.827Z
Learnt from: asafbennatan
Repo: flightctl/ai-workflows PR: 99
File: pr-review/skills/start.md:0-0
Timestamp: 2026-08-06T13:07:53.827Z
Learning: In Markdown templates containing nested triple-backtick code fences, wrap the outer template block with a fence of at least four backticks. This prevents inner triple-backtick fences from prematurely terminating the outer block and preserves correct Markdown rendering.
Applied to files:
design/SKILL.mdprd/SKILL.mdAGENTS.mdprd/skills/controller.mddesign/README.mdprd/skills/revise.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mdprd/GUIDE.mdimplement/SKILL.mde2e/skills/ingest.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.mdimplement/skills/ingest.mdprd/skills/clarify.mde2e/SKILL.mdprd/skills/publish.mdprd/skills/respond.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:
prd/skills/controller.mdprd/skills/revise.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mde2e/skills/ingest.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.mdimplement/skills/ingest.mdprd/skills/clarify.mdprd/skills/publish.mdprd/skills/respond.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:
prd/skills/controller.mdprd/skills/revise.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mde2e/skills/ingest.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.mdimplement/skills/ingest.mdprd/skills/clarify.mdprd/skills/publish.mdprd/skills/respond.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:
prd/skills/controller.mdprd/skills/revise.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mde2e/skills/ingest.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.mdimplement/skills/ingest.mdprd/skills/clarify.mdprd/skills/publish.mdprd/skills/respond.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:
prd/skills/controller.mdprd/skills/revise.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mde2e/skills/ingest.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.mdimplement/skills/ingest.mdprd/skills/clarify.mdprd/skills/publish.mdprd/skills/respond.md
📚 Learning: 2026-07-27T19:10:53.566Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 85
File: design/skills/publish.md:103-103
Timestamp: 2026-07-27T19:10:53.566Z
Learning: In flightctl/ai-workflows skill markdown workflows under {design,prd}/skills/ (e.g., publish/revise/respond), do not hardcode downstream branch names like `prd/{issue-key}` or `design/{issue-key}`. Instead, follow the existing `{branch-name}` propagation convention used by the implement and e2e workflows, and ensure downstream commands pass through the `{branch-name}` value consistently across publish, revise, and respond steps.
Applied to files:
prd/skills/controller.mdprd/skills/revise.mddesign/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.mdprd/skills/clarify.mdprd/skills/publish.mdprd/skills/respond.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:
design/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.md
📚 Learning: 2026-04-12T00:25:49.194Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/revise.md:32-37
Timestamp: 2026-04-12T00:25:49.194Z
Learning: In `design/skills/*.md` (e.g., `design/skills/revise.md`, `design/skills/respond.md`) the AI agent “runtime file path” instructions must use repo-root-relative paths (the agent executes from the repo root). For example, use paths like `.artifacts/design/{issue-number}/02-design.md` rather than `../../.artifacts/...`. Only apply relative-path path fixes to actual markdown hyperlink/reference syntax; do not rewrite these prose runtime path instructions.
Applied to files:
design/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.md
📚 Learning: 2026-07-28T19:55:45.514Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/publish.md:165-180
Timestamp: 2026-07-28T19:55:45.514Z
Learning: When reviewing the design workflow documentation under design/skills/*.md, account for the intended publication/sync order: design/skills/publish.md publishes the docs repo before sync, so feature-local Story identifiers in 07-testplan.md are expected at that stage and should not be treated as errors. design/skills/respond.md and design/skills/revise.md should only resolve published testplan Story fields via sync-manifest.json when it exists; if sync-manifest.json is absent, leaving fields un-resolved is expected. design/skills/sync.md is responsible for Jira-key resolution and should report any references it cannot resolve while preserving the original unresolved references as-is.
Applied to files:
design/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.md
📚 Learning: 2026-07-28T19:56:19.476Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/sync.md:639-647
Timestamp: 2026-07-28T19:56:19.476Z
Learning: When writing/reviewing downstream phases in the design workflow that update the published docs repository, do not assume a hardcoded default branch name. Instead, read the `branch` value from `.artifacts/design/{issue-key}/publish-metadata.json` (produced by the publish step) and use that branch for any subsequent published-docs operations so user overrides are honored.
Applied to files:
design/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.md
📚 Learning: 2026-07-28T21:51:15.223Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 86
File: design/skills/respond.md:32-36
Timestamp: 2026-07-28T21:51:15.223Z
Learning: In this repo’s “design skills” flows that consume `publish-metadata.json`, treat it as a trusted internal artifact produced by the `/publish` workflow: downstream PRD/design skills may rely on fields like `branch` only after the consumer verifies that the metadata file exists. If a metadata field is missing or empty, the schema/field validation should be implemented in the `/publish` producer (the source of `publish-metadata.json`) rather than duplicated in every downstream consumer, matching the current handling in the implement/e2e workflows for internally generated branch data.
Applied to files:
design/skills/controller.mddesign/skills/decompose.mddesign/skills/respond.mddesign/skills/ingest.mddesign/skills/revise.mddesign/skills/draft.mddesign/skills/research.mddesign/skills/sync.mddesign/skills/publish.md
📚 Learning: 2026-04-27T16:15:33.140Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 32
File: design/skills/research.md:68-70
Timestamp: 2026-04-27T16:15:33.140Z
Learning: In flightctl/ai-workflows, the `design` workflow phases `/research` and `/draft` are intended to be started “from scratch.” During these phases, it is expected that the code reads both `.artifacts/design/{issue-number}/01-context.md` (for architectural orientation) AND the full PRD artifacts `.artifacts/prd/{issue-number}/03-prd.md` and `.artifacts/prd/{issue-number}/02-clarifications.md` to capture complete requirement detail and locked decisions. Only later phases that refine existing design artifacts (e.g., `/revise`) should rely on `01-context.md` as the authoritative requirement bridge and avoid re-reading the full PRD. Therefore, do not flag direct PRD reads as a policy mismatch specifically in `/research` or `/draft`.
Applied to files:
design/skills/draft.mddesign/skills/research.md
🪛 LanguageTool
AGENTS.md
[grammar] ~88-~88: Please add a punctuation mark at the end of paragraph.
Context: ... testplans), and workspace-level config at .artifacts/config.json ## Workflow V...
(PUNCTUATION_PARAGRAPH_END)
design/skills/draft.md
[style] ~145-~145: Consider using the typographical ellipsis character here instead.
Context: ... functional requirement (FR-1, FR-2, ...) and non-functional requirement (NFR-1,...
(ELLIPSIS)
[style] ~146-~146: Consider using the typographical ellipsis character here instead.
Context: ...unctional requirement (NFR-1, NFR-2, ...), confirm it is addressed in the design...
(ELLIPSIS)
design/skills/publish.md
[style] ~101-~101: This word has been used in one of the immediately preceding sentences. Using a synonym could make your text more interesting to read, unless the repetition is intentional.
Context: ...6-Q2). If a PRD directory was found, propose the extracted release` value as the ...
(EN_REPEATEDWORDS_PROPOSE)
[style] ~105-~105: This word has been used in one of the immediately preceding sentences. Using a synonym could make your text more interesting to read, unless the repetition is intentional.
Context: ...1471). If a PRD directory was found, propose the extracted feature` value as the ...
(EN_REPEATEDWORDS_PROPOSE)
[style] ~106-~106: This word has been used in one of the immediately preceding sentences. Using a synonym could make your text more interesting to read, unless the repetition is intentional.
Context: ...ure` value as the default. Otherwise, suggest a slug derived from the Jira issue summ...
(EN_REPEATEDWORDS_SUGGEST)
prd/skills/clarify.md
[style] ~113-~113: Since ownership is already implied, this phrasing may be redundant.
Context: ...h field (Answer, Impact, Decision) gets its own heading. Never collapse multiple fields...
(PRP_OWN)
[style] ~179-~179: Consider using the typographical ellipsis character here instead.
Context: ...sequentially across all rounds (D1, D2, ... D{N}) ### Step 5: Check Exit Criteria ...
(ELLIPSIS)
🔇 Additional comments (16)
design/skills/controller.md (1)
69-74: LGTM!e2e/skills/ingest.md (1)
101-103: LGTM!Also applies to: 118-119
implement/SKILL.md (1)
3-3: LGTM!implement/skills/ingest.md (1)
92-94: LGTM!Also applies to: 109-110
e2e/SKILL.md (1)
3-3: LGTM!prd/SKILL.md (1)
3-3: LGTM!prd/skills/clarify.md (1)
102-114: LGTM!Also applies to: 127-180
prd/skills/publish.md (1)
34-34: LGTM!Also applies to: 54-54, 164-171, 205-205, 239-242
prd/skills/respond.md (1)
37-37: LGTM!Also applies to: 125-128, 199-199
design/skills/respond.md (1)
37-37: LGTM!design/skills/revise.md (1)
114-115: LGTM!Also applies to: 167-167
design/README.md (1)
48-48: LGTM!design/skills/ingest.md (1)
157-157: LGTM!design/skills/publish.md (1)
34-34: LGTM!Also applies to: 54-54, 310-310
design/skills/decompose.md (1)
682-682: LGTM!design/skills/draft.md (1)
41-43: LGTM!Also applies to: 144-152
…presence - design/skills/ingest.md: Validate existing .artifacts/config.json before use (path exists, is git repo, remote matches) — same checks as publish - design/skills/ingest.md: Filter find matches to directories containing prd.md before using them - design/skills/decompose.md: Distinguish Jira lookup failures from unset fields in sizing check — report errors, only skip on successful read with no size set Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>
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 `@design/skills/decompose.md`:
- Around line 352-357: Define the Jira sizing contract in the Feature size
lookup step: specify how numeric Story Points map to the T-shirt sizes used by
the epic comparison, including supported ranges and boundary behavior.
Alternatively, require the Size field for this plausibility check and explicitly
state what happens when only Story Points is available; keep the producer and
consumer field names and types consistent.
In `@design/skills/ingest.md`:
- Around line 64-74: Update the existing-config validation flow to persist
corrected docs_repo_path and docs_repo_remote values to .artifacts/config.json
after the user-provided values pass all validation checks, before continuing.
Preserve the current re-prompt behavior for invalid values and keep the same
configuration keys used by later workflows.
🪄 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: a617eff2-bd69-485a-8c28-379db1d3665a
📒 Files selected for processing (2)
design/skills/decompose.mddesign/skills/ingest.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (3)
**/{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:
design/skills/decompose.mddesign/skills/ingest.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 and must not contain IDE-specific syntax.
All file references in workflow Markdown must be relative to the referencing file's location.
Workflows must not auto-advance in attended mode; they must wait for user input between phases unless explicit unattended mode is documented.
Significant workflow outputs must be saved under.artifacts/{workflow-name}/{context}/.
Each workflow's.artifacts/{workflow-name}/directory is private; other workflows must never read from or write to another workflow's artifact directory.
Before applying documentation changes to repository files, run Vale validation.
Before destructive Git operations, verify withgit status; before creating or pushing a PR/MR, confirm the branch and base.
Onlycve-fix /close,design /sync, andsizing /applymay write to Jira, and each requires explicit approval.
Files:
design/skills/decompose.mddesign/skills/ingest.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:
design/skills/decompose.mddesign/skills/ingest.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.
Projects may override workflow phases with
.workflows/{workflow}/skills/{phase}.md; controllers must check for and activate this override before the built-in phase skill.
Files:
design/skills/decompose.mddesign/skills/ingest.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:
design/skills/decompose.mddesign/skills/ingest.md
🧠 Learnings (12)
📚 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:
design/skills/decompose.mddesign/skills/ingest.md
📚 Learning: 2026-04-12T00:25:49.194Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/revise.md:32-37
Timestamp: 2026-04-12T00:25:49.194Z
Learning: In `design/skills/*.md` (e.g., `design/skills/revise.md`, `design/skills/respond.md`) the AI agent “runtime file path” instructions must use repo-root-relative paths (the agent executes from the repo root). For example, use paths like `.artifacts/design/{issue-number}/02-design.md` rather than `../../.artifacts/...`. Only apply relative-path path fixes to actual markdown hyperlink/reference syntax; do not rewrite these prose runtime path instructions.
Applied to files:
design/skills/decompose.mddesign/skills/ingest.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:
design/skills/decompose.mddesign/skills/ingest.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:
design/skills/decompose.mddesign/skills/ingest.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:
design/skills/decompose.mddesign/skills/ingest.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:
design/skills/decompose.mddesign/skills/ingest.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:
design/skills/decompose.mddesign/skills/ingest.md
📚 Learning: 2026-08-06T13:07:53.827Z
Learnt from: asafbennatan
Repo: flightctl/ai-workflows PR: 99
File: pr-review/skills/start.md:0-0
Timestamp: 2026-08-06T13:07:53.827Z
Learning: In Markdown templates containing nested triple-backtick code fences, wrap the outer template block with a fence of at least four backticks. This prevents inner triple-backtick fences from prematurely terminating the outer block and preserves correct Markdown rendering.
Applied to files:
design/skills/decompose.mddesign/skills/ingest.md
📚 Learning: 2026-07-27T19:10:53.566Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 85
File: design/skills/publish.md:103-103
Timestamp: 2026-07-27T19:10:53.566Z
Learning: In flightctl/ai-workflows skill markdown workflows under {design,prd}/skills/ (e.g., publish/revise/respond), do not hardcode downstream branch names like `prd/{issue-key}` or `design/{issue-key}`. Instead, follow the existing `{branch-name}` propagation convention used by the implement and e2e workflows, and ensure downstream commands pass through the `{branch-name}` value consistently across publish, revise, and respond steps.
Applied to files:
design/skills/decompose.mddesign/skills/ingest.md
📚 Learning: 2026-07-28T19:55:45.514Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/publish.md:165-180
Timestamp: 2026-07-28T19:55:45.514Z
Learning: When reviewing the design workflow documentation under design/skills/*.md, account for the intended publication/sync order: design/skills/publish.md publishes the docs repo before sync, so feature-local Story identifiers in 07-testplan.md are expected at that stage and should not be treated as errors. design/skills/respond.md and design/skills/revise.md should only resolve published testplan Story fields via sync-manifest.json when it exists; if sync-manifest.json is absent, leaving fields un-resolved is expected. design/skills/sync.md is responsible for Jira-key resolution and should report any references it cannot resolve while preserving the original unresolved references as-is.
Applied to files:
design/skills/decompose.mddesign/skills/ingest.md
📚 Learning: 2026-07-28T19:56:19.476Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/sync.md:639-647
Timestamp: 2026-07-28T19:56:19.476Z
Learning: When writing/reviewing downstream phases in the design workflow that update the published docs repository, do not assume a hardcoded default branch name. Instead, read the `branch` value from `.artifacts/design/{issue-key}/publish-metadata.json` (produced by the publish step) and use that branch for any subsequent published-docs operations so user overrides are honored.
Applied to files:
design/skills/decompose.mddesign/skills/ingest.md
📚 Learning: 2026-07-28T21:51:15.223Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 86
File: design/skills/respond.md:32-36
Timestamp: 2026-07-28T21:51:15.223Z
Learning: In this repo’s “design skills” flows that consume `publish-metadata.json`, treat it as a trusted internal artifact produced by the `/publish` workflow: downstream PRD/design skills may rely on fields like `branch` only after the consumer verifies that the metadata file exists. If a metadata field is missing or empty, the schema/field validation should be implemented in the `/publish` producer (the source of `publish-metadata.json`) rather than duplicated in every downstream consumer, matching the current handling in the implement/e2e workflows for internally generated branch data.
Applied to files:
design/skills/decompose.mddesign/skills/ingest.md
🪛 LanguageTool
design/skills/ingest.md
[style] ~73-~73: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...r and re-ask for the correct values. If the config does not exist, ask the us...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🔇 Additional comments (4)
design/skills/ingest.md (3)
92-93: 🗄️ Data Integrity & IntegrationRestrict the manual PRD fallback to the validated docs repository.
When discovery finds no match, the workflow asks for a PRD path without requiring that the path is inside
docs_repo_pathor that it containsprd.md. This bypasses the authoritative published PRD boundary.Require the fallback path to be inside the validated docs repository. Verify that it is readable and points to
prd.mdbefore using it.As per path instructions, cross-workflow inputs must preserve a consistent file contract.
Source: Path instructions
84-90: LGTM!
97-109: LGTM!Also applies to: 168-168
design/skills/decompose.md (1)
685-685: LGTM!
prd/skills/controller.md still said config was created by /publish only. Updated to match design controller: created by whichever workflow's /publish or /ingest phase runs first. Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>
When existing .artifacts/config.json fails validation, the re-asked values are now written back to config.json so downstream workflows don't re-encounter the stale values. Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
design/skills/ingest.md (3)
62-62: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winUse full step numbers for sequential operations.
3a,3b,3c, and3dare sequential workflow stages. They are not conditional branches. Promote them to numbered steps, or make them unnumbered bullets under Step 3. Update later references such asStep 6aafter renumbering.As per path instructions, sub-steps are allowed only for conditional branches off the parent step.
Also applies to: 77-77, 96-96, 105-105
🤖 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 `@design/skills/ingest.md` at line 62, Renumber the sequential workflow stages currently labeled 3a, 3b, 3c, and 3d as full numbered steps, or convert them to unnumbered bullets under Step 3; update all later references, including Step 6a, to match the revised numbering. Reserve lettered sub-steps only for conditional branches.Source: Path instructions
93-94:⚠️ Potential issue | 🟠 MajorRestrict the no-match fallback to the validated docs repository.
This fallback accepts any user-supplied PRD path. The agent can read
.artifacts/prd/...or another repository, which conflicts with the authoritative published PRD rule and the artifact-isolation objective. Require the fallback path to be underdocs_repo_path, verify that it is a readableprd.md, and use its co-locatedclarifications.mdonly.🤖 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 `@design/skills/ingest.md` around lines 93 - 94, Update the no-match fallback in the PRD ingestion flow to accept only a user-supplied path under docs_repo_path; reject paths outside that repository, validate that the target is a readable prd.md, and load only its co-located clarifications.md.
107-110: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick winDefine the PRD path contract before downstream use.
ingest.mdrecords both paths without specifying their format. Downstream skills consume these values, while the design template requires a relative link toprd.md. Define the stored path format and the conversion to the relative design-document link for both the PRD and clarifications.🤖 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 `@design/skills/ingest.md` around lines 107 - 110, Update the PRD Summary instructions in ingest.md to define a consistent stored path format for the resolved PRD and clarifications paths, and specify how each is converted into the relative link required by the design template. Ensure downstream skills can consume the stored values directly while the generated design document links to prd.md and the clarifications file correctly.
🤖 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.
Outside diff comments:
In `@design/skills/ingest.md`:
- Line 62: Renumber the sequential workflow stages currently labeled 3a, 3b, 3c,
and 3d as full numbered steps, or convert them to unnumbered bullets under Step
3; update all later references, including Step 6a, to match the revised
numbering. Reserve lettered sub-steps only for conditional branches.
- Around line 93-94: Update the no-match fallback in the PRD ingestion flow to
accept only a user-supplied path under docs_repo_path; reject paths outside that
repository, validate that the target is a readable prd.md, and load only its
co-located clarifications.md.
- Around line 107-110: Update the PRD Summary instructions in ingest.md to
define a consistent stored path format for the resolved PRD and clarifications
paths, and specify how each is converted into the relative link required by the
design template. Ensure downstream skills can consume the stored values directly
while the generated design document links to prd.md and the clarifications file
correctly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 6ec8838b-5c76-41d8-aa70-69b4d63e84eb
📒 Files selected for processing (1)
design/skills/ingest.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (3)
**/{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:
design/skills/ingest.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 without IDE-specific syntax.
All file references in workflow documentation must be relative to the referencing file's location for symlink compatibility.
In attended mode, workflows must not auto-advance between phases unless that workflow explicitly documents unattended mode.
Before applying documentation changes to repository files, run Vale validation.
For commands affecting shared systems, verifygit 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:
design/skills/ingest.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:
design/skills/ingest.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 a project provides a phase override, the controller must check
.workflows/{workflow}/skills/{phase}.mdbefore using the built-in phase skill.
Files:
design/skills/ingest.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:
design/skills/ingest.md
🧠 Learnings (12)
📚 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:
design/skills/ingest.md
📚 Learning: 2026-04-12T00:25:49.194Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/revise.md:32-37
Timestamp: 2026-04-12T00:25:49.194Z
Learning: In `design/skills/*.md` (e.g., `design/skills/revise.md`, `design/skills/respond.md`) the AI agent “runtime file path” instructions must use repo-root-relative paths (the agent executes from the repo root). For example, use paths like `.artifacts/design/{issue-number}/02-design.md` rather than `../../.artifacts/...`. Only apply relative-path path fixes to actual markdown hyperlink/reference syntax; do not rewrite these prose runtime path instructions.
Applied to files:
design/skills/ingest.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:
design/skills/ingest.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:
design/skills/ingest.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:
design/skills/ingest.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:
design/skills/ingest.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:
design/skills/ingest.md
📚 Learning: 2026-08-06T13:07:53.827Z
Learnt from: asafbennatan
Repo: flightctl/ai-workflows PR: 99
File: pr-review/skills/start.md:0-0
Timestamp: 2026-08-06T13:07:53.827Z
Learning: In Markdown templates containing nested triple-backtick code fences, wrap the outer template block with a fence of at least four backticks. This prevents inner triple-backtick fences from prematurely terminating the outer block and preserves correct Markdown rendering.
Applied to files:
design/skills/ingest.md
📚 Learning: 2026-07-27T19:10:53.566Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 85
File: design/skills/publish.md:103-103
Timestamp: 2026-07-27T19:10:53.566Z
Learning: In flightctl/ai-workflows skill markdown workflows under {design,prd}/skills/ (e.g., publish/revise/respond), do not hardcode downstream branch names like `prd/{issue-key}` or `design/{issue-key}`. Instead, follow the existing `{branch-name}` propagation convention used by the implement and e2e workflows, and ensure downstream commands pass through the `{branch-name}` value consistently across publish, revise, and respond steps.
Applied to files:
design/skills/ingest.md
📚 Learning: 2026-07-28T19:55:45.514Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/publish.md:165-180
Timestamp: 2026-07-28T19:55:45.514Z
Learning: When reviewing the design workflow documentation under design/skills/*.md, account for the intended publication/sync order: design/skills/publish.md publishes the docs repo before sync, so feature-local Story identifiers in 07-testplan.md are expected at that stage and should not be treated as errors. design/skills/respond.md and design/skills/revise.md should only resolve published testplan Story fields via sync-manifest.json when it exists; if sync-manifest.json is absent, leaving fields un-resolved is expected. design/skills/sync.md is responsible for Jira-key resolution and should report any references it cannot resolve while preserving the original unresolved references as-is.
Applied to files:
design/skills/ingest.md
📚 Learning: 2026-07-28T19:56:19.476Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/sync.md:639-647
Timestamp: 2026-07-28T19:56:19.476Z
Learning: When writing/reviewing downstream phases in the design workflow that update the published docs repository, do not assume a hardcoded default branch name. Instead, read the `branch` value from `.artifacts/design/{issue-key}/publish-metadata.json` (produced by the publish step) and use that branch for any subsequent published-docs operations so user overrides are honored.
Applied to files:
design/skills/ingest.md
📚 Learning: 2026-07-28T21:51:15.223Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 86
File: design/skills/respond.md:32-36
Timestamp: 2026-07-28T21:51:15.223Z
Learning: In this repo’s “design skills” flows that consume `publish-metadata.json`, treat it as a trusted internal artifact produced by the `/publish` workflow: downstream PRD/design skills may rely on fields like `branch` only after the consumer verifies that the metadata file exists. If a metadata field is missing or empty, the schema/field validation should be implemented in the `/publish` producer (the source of `publish-metadata.json`) rather than duplicated in every downstream consumer, matching the current handling in the implement/e2e workflows for internally generated branch data.
Applied to files:
design/skills/ingest.md
🔇 Additional comments (1)
design/skills/ingest.md (1)
59-61: LGTM!Also applies to: 64-75, 79-92, 98-103, 169-169
3a/3b/3c/3d were sequential operations, not conditional branches. Converted to unnumbered headings under Step 3 per the project convention that lettered sub-steps are reserved for conditional branches only. Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>
|
@coderabbitai Responding to outside-diff comments from review 4877367524: Line 62 — sub-step numbering (3a/3b/3c/3d): Fixed in 5bcc40c — converted to unnumbered Lines 93-94 — restrict fallback path to docs repo: No change. When automatic discovery fails, the user provides a path. Restricting it to the docs repo would prevent legitimate cases (user has the PRD in a different location, non-standard docs repo layout, etc.). The human is in the loop — they'll provide a valid path. Lines 107-110 — define stored path format: No change. The stored path is whatever filesystem path the AI resolved. The design template's |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '== Changed files relevant to the response =='
git diff --name-only origin/main...HEAD | rg '(^|/)(ingest|draft|research|decompose)\.md$|design/README\.md' || true
printf '%s\n' '== Outline: design/skills/ingest.md =='
ast-grep outline design/skills/ingest.md --items all 2>/dev/null || true
printf '%s\n' '== Step 3 and context recording in design/skills/ingest.md =='
rg -n -C 8 'Step 3|3a|3b|3c|3d|fallback|manual|path|01-context\.md|PRD Summary|clarifications' design/skills/ingest.md
printf '%s\n' '== Downstream consumption of recorded PRD and clarifications paths =='
rg -n -C 4 '01-context\.md|PRD path|Clarifications path|PRD Summary|clarifications path' \
design/skills/draft.md \
design/skills/research.md \
design/skills/decompose.md \
design/skills/revise.md \
design/skills/respond.md 2>/dev/null || true
printf '%s\n' '== Commit 5bcc40c summary =='
git show --stat --oneline --no-renames 5bcc40c --
git show --format= --no-ext-diff --unified=12 5bcc40c -- design/skills/ingest.mdLength of output: 22616
I will keep the other two findings open.
🐇🔎 ✏️ Learnings added
You are interacting with an AI system. |
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
design/skills/ingest.md (1)
77-95: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winComplete the manual PRD fallback contract.
When discovery finds no candidate, the workflow only asks for a PRD path. It does not require the agent to verify that the file exists, read it, or confirm it before recording the path.
The clarification lookup also targets the “same docs repo directory.” A permitted fallback outside the docs repository can therefore skip a co-located
clarifications.mdand its locked decisions.After the user provides a fallback path:
- Verify that the file exists and is readable.
- Read the PRD before compiling context.
- Resolve
clarifications.mdfrom the directory containing the resolved PRD.- Record the paths only after these checks succeed.
This keeps the fallback unrestricted while preventing incomplete design context.
As per path instructions, workflow failure modes and cross-file path contracts must be explicit. Based on the PR objective, manual fallback paths may remain outside the docs repository.
Suggested wording change
If no match is found (or no matches contain `prd.md`), ask the user for -the path to the PRD. +the path to the PRD. Verify that the selected file exists and is readable, +then read it before continuing. -If `clarifications.md` exists in the same docs repo directory as the PRD, +If `clarifications.md` exists in the directory containing the resolved PRD, read it. Note any locked decisions — these are binding constraints for the design.Also applies to: 96-110
🤖 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 `@design/skills/ingest.md` around lines 77 - 95, Update the PRD discovery fallback workflow in “Find the PRD in the Docs Repo” so a user-provided path may be outside the docs repository but must be verified as existing and readable, then read before compiling context. Resolve any clarifications.md from the resolved PRD’s containing directory rather than the docs repo directory, and record the PRD and clarification paths only after validation and reading succeed; explicitly document failure handling for invalid or unreadable paths and apply the same contract to the related clarification lookup section.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.
Outside diff comments:
In `@design/skills/ingest.md`:
- Around line 77-95: Update the PRD discovery fallback workflow in “Find the PRD
in the Docs Repo” so a user-provided path may be outside the docs repository but
must be verified as existing and readable, then read before compiling context.
Resolve any clarifications.md from the resolved PRD’s containing directory
rather than the docs repo directory, and record the PRD and clarification paths
only after validation and reading succeed; explicitly document failure handling
for invalid or unreadable paths and apply the same contract to the related
clarification lookup section.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: dfbd1622-7188-4ce3-8a70-610f776fb268
📒 Files selected for processing (1)
design/skills/ingest.md
📜 Review details
🧰 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:
design/skills/ingest.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).Workflow content must use plain Markdown without IDE-specific syntax.
Files:
design/skills/ingest.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:
design/skills/ingest.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.
Workflows should use discrete phases with explicit transitions, and controllers should support project phase overrides from
.workflows/{workflow}/skills/{phase}.mdbefore built-in defaults.
Files:
design/skills/ingest.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:
design/skills/ingest.md
**/{SKILL.md,guidelines.md,skills/**/*.md,commands/**/*.md,templates/**/*.md,prompts/**/*.md}
📄 CodeRabbit inference engine (AGENTS.md)
All file references in workflow content must be relative to the referencing file's location for symlink compatibility.
Files:
design/skills/ingest.md
**/{SKILL.md,guidelines.md,skills/**/*.md,commands/**/*.md,templates/**/*.md,prompts/**/*.md,scripts/**/*,_shared/**/*.md}
📄 CodeRabbit inference engine (AGENTS.md)
**/{SKILL.md,guidelines.md,skills/**/*.md,commands/**/*.md,templates/**/*.md,prompts/**/*.md,scripts/**/*,_shared/**/*.md}: Significant workflow outputs must be persisted under.artifacts/{workflow-name}/{context}/; workflows must not read from or write to another workflow's artifact directory.
Behavioral workflow changes must include the corresponding version bump in the same commit;README.mdandGUIDE.mdchanges do not require a bump.
Files:
design/skills/ingest.md
**/*.{md,py}
📄 CodeRabbit inference engine (AGENTS.md)
When modifying workflow behavior, preserve the canonical workflow structure:
SKILL.md,guidelines.md,README.md, optionalskills/,commands/,scripts/, andprompts/directories.
Files:
design/skills/ingest.md
**/skills/**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
**/skills/**/*.md: Attended-mode workflows must not auto-advance between phases unless that workflow explicitly documents an unattended mode.
Operations affecting shared systems require safeguards: verifygit statusbefore destructive Git operations; confirm branch and base before PR/MR pushes; require explicit approval for Jira writes by cve-fix/close, design/sync, and sizing/apply; and run Vale before applying documentation changes.
Files:
design/skills/ingest.md
🧠 Learnings (12)
📚 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:
design/skills/ingest.md
📚 Learning: 2026-04-12T00:25:49.194Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/revise.md:32-37
Timestamp: 2026-04-12T00:25:49.194Z
Learning: In `design/skills/*.md` (e.g., `design/skills/revise.md`, `design/skills/respond.md`) the AI agent “runtime file path” instructions must use repo-root-relative paths (the agent executes from the repo root). For example, use paths like `.artifacts/design/{issue-number}/02-design.md` rather than `../../.artifacts/...`. Only apply relative-path path fixes to actual markdown hyperlink/reference syntax; do not rewrite these prose runtime path instructions.
Applied to files:
design/skills/ingest.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:
design/skills/ingest.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:
design/skills/ingest.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:
design/skills/ingest.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:
design/skills/ingest.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:
design/skills/ingest.md
📚 Learning: 2026-08-06T13:07:53.827Z
Learnt from: asafbennatan
Repo: flightctl/ai-workflows PR: 99
File: pr-review/skills/start.md:0-0
Timestamp: 2026-08-06T13:07:53.827Z
Learning: In Markdown templates containing nested triple-backtick code fences, wrap the outer template block with a fence of at least four backticks. This prevents inner triple-backtick fences from prematurely terminating the outer block and preserves correct Markdown rendering.
Applied to files:
design/skills/ingest.md
📚 Learning: 2026-07-27T19:10:53.566Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 85
File: design/skills/publish.md:103-103
Timestamp: 2026-07-27T19:10:53.566Z
Learning: In flightctl/ai-workflows skill markdown workflows under {design,prd}/skills/ (e.g., publish/revise/respond), do not hardcode downstream branch names like `prd/{issue-key}` or `design/{issue-key}`. Instead, follow the existing `{branch-name}` propagation convention used by the implement and e2e workflows, and ensure downstream commands pass through the `{branch-name}` value consistently across publish, revise, and respond steps.
Applied to files:
design/skills/ingest.md
📚 Learning: 2026-07-28T19:55:45.514Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/publish.md:165-180
Timestamp: 2026-07-28T19:55:45.514Z
Learning: When reviewing the design workflow documentation under design/skills/*.md, account for the intended publication/sync order: design/skills/publish.md publishes the docs repo before sync, so feature-local Story identifiers in 07-testplan.md are expected at that stage and should not be treated as errors. design/skills/respond.md and design/skills/revise.md should only resolve published testplan Story fields via sync-manifest.json when it exists; if sync-manifest.json is absent, leaving fields un-resolved is expected. design/skills/sync.md is responsible for Jira-key resolution and should report any references it cannot resolve while preserving the original unresolved references as-is.
Applied to files:
design/skills/ingest.md
📚 Learning: 2026-07-28T19:56:19.476Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/sync.md:639-647
Timestamp: 2026-07-28T19:56:19.476Z
Learning: When writing/reviewing downstream phases in the design workflow that update the published docs repository, do not assume a hardcoded default branch name. Instead, read the `branch` value from `.artifacts/design/{issue-key}/publish-metadata.json` (produced by the publish step) and use that branch for any subsequent published-docs operations so user overrides are honored.
Applied to files:
design/skills/ingest.md
📚 Learning: 2026-07-28T21:51:15.223Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 86
File: design/skills/respond.md:32-36
Timestamp: 2026-07-28T21:51:15.223Z
Learning: In this repo’s “design skills” flows that consume `publish-metadata.json`, treat it as a trusted internal artifact produced by the `/publish` workflow: downstream PRD/design skills may rely on fields like `branch` only after the consumer verifies that the metadata file exists. If a metadata field is missing or empty, the schema/field validation should be implemented in the `/publish` producer (the source of `publish-metadata.json`) rather than duplicated in every downstream consumer, matching the current handling in the implement/e2e workflows for internally generated branch data.
Applied to files:
design/skills/ingest.md
🔇 Additional comments (1)
design/skills/ingest.md (1)
62-75: LGTM!Also applies to: 105-110, 169-169
- Verify user-provided PRD path exists and is readable before recording - Look for clarifications.md in the directory containing the resolved PRD, not specifically the docs repo directory — supports fallback paths outside the docs repo Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>
|
@coderabbitai Fixed in 3d461ae — user-provided fallback paths are now verified as existing and readable before recording. Clarifications lookup changed from "same docs repo directory" to "directory containing the resolved PRD" so it works regardless of where the PRD lives. |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '== Commit 3d461ae =='
git show --format=fuller --stat --no-renames 3d461ae --
git show --format= --no-ext-diff --unified=18 3d461ae -- design/skills/ingest.md
printf '%s\n' '== Current relevant instructions in design/skills/ingest.md =='
rg -n -C 10 'fallback|manual|provided path|readable|exists|resolve|absolute|relative|Clarifications|01-context\.md|PRD Summary' design/skills/ingest.md
printf '%s\n' '== Consumers of recorded paths =='
rg -n -C 5 'PRD path|Clarifications path|PRD Summary|01-context\.md|resolved PRD' \
design/skills/draft.md \
design/skills/research.md \
design/skills/decompose.md \
design/skills/revise.md \
design/skills/respond.mdLength of output: 23613
I will keep both findings open.
✏️ Learnings added
You are interacting with an AI system. |
design/skills/ingest.md had the write-back but the same validate-and-re-ask pattern in design/publish, prd/publish, implement/ingest, and e2e/ingest did not persist corrected values. A stale config would cause repeated re-prompts on every invocation from any workflow. Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
design/skills/ingest.md (1)
106-111: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winDefine the stored path format.
This step records the resolved paths but does not specify whether they are absolute, workspace-root-relative, or relative to the docs repository.
design/skills/research.mdconsumes the PRD Summary path directly in Lines 69-70. Define one format here and require downstream phases to use the same format.As per path instructions, cross-workflow file references must use one consistent, symlink-safe path convention.
🤖 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 `@design/skills/ingest.md` around lines 106 - 111, Define the path format in the “Record the Resolved Paths” step, using one symlink-safe convention for both the PRD and optional clarifications paths. Require the stored values in `.artifacts/design/{issue-key}/01-context.md` and consumers such as `/research` to use that same convention consistently.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 `@design/skills/ingest.md`:
- Around line 94-95: Update the fallback PRD ingestion instructions around the
existing path validation so the workflow explicitly asks the user to confirm
that the readable file is the current authoritative PRD before reading or
ingesting it. Keep the fallback path unrestricted and retain the existing
existence and readability checks.
- Around line 99-100: Update the clarification-loading instructions around
clarifications.md to require that an existing file is readable before processing
its contents. If readability validation fails, stop ingestion and ask the user
how to proceed; only continue to note locked decisions after the file is
successfully read.
---
Outside diff comments:
In `@design/skills/ingest.md`:
- Around line 106-111: Define the path format in the “Record the Resolved Paths”
step, using one symlink-safe convention for both the PRD and optional
clarifications paths. Require the stored values in
`.artifacts/design/{issue-key}/01-context.md` and consumers such as `/research`
to use that same convention consistently.
🪄 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: f9a96ee3-5b4a-4cf2-b345-b4b71ebb290a
📒 Files selected for processing (1)
design/skills/ingest.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (6)
**/{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:
design/skills/ingest.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).All workflow content must use plain Markdown and must not use IDE-specific syntax.
Files:
design/skills/ingest.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:
design/skills/ingest.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.
**/skills/*.md: Workflows should operate through discrete phases with explicit transitions.
Attended-mode workflows must not auto-advance; they must wait for user input between phases unless documented unattended mode is explicitly supported.
Files:
design/skills/ingest.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:
design/skills/ingest.md
**/*.{md,py,sh,json}
📄 CodeRabbit inference engine (AGENTS.md)
All file references used by workflows must be relative to the referencing file's location for symlink compatibility.
Files:
design/skills/ingest.md
**/*
📄 CodeRabbit inference engine (AGENTS.md)
**/*: Significant workflow outputs must be persisted under.artifacts/{workflow-name}/{context}/.
Each workflow's.artifacts/{workflow-name}/directory is private; other workflows must never read from or write to it.
Before destructive Git operations, verify the working state withgit status.
Before creating or pushing a PR/MR, confirm the branch and base branch.
Run Vale validation before applying documentation changes to repository files.
Files:
design/skills/ingest.md
**/{SKILL.md,guidelines.md,skills/*.md,commands/*.md,templates/*,prompts/*,scripts/*}
📄 CodeRabbit inference engine (AGENTS.md)
Behavioral workflow files require a version bump when modified;
README.mdandGUIDE.mddo not require one.
Files:
design/skills/ingest.md
🧠 Learnings (12)
📚 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:
design/skills/ingest.md
📚 Learning: 2026-04-12T00:25:49.194Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/revise.md:32-37
Timestamp: 2026-04-12T00:25:49.194Z
Learning: In `design/skills/*.md` (e.g., `design/skills/revise.md`, `design/skills/respond.md`) the AI agent “runtime file path” instructions must use repo-root-relative paths (the agent executes from the repo root). For example, use paths like `.artifacts/design/{issue-number}/02-design.md` rather than `../../.artifacts/...`. Only apply relative-path path fixes to actual markdown hyperlink/reference syntax; do not rewrite these prose runtime path instructions.
Applied to files:
design/skills/ingest.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:
design/skills/ingest.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:
design/skills/ingest.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:
design/skills/ingest.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:
design/skills/ingest.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:
design/skills/ingest.md
📚 Learning: 2026-08-06T13:07:53.827Z
Learnt from: asafbennatan
Repo: flightctl/ai-workflows PR: 99
File: pr-review/skills/start.md:0-0
Timestamp: 2026-08-06T13:07:53.827Z
Learning: In Markdown templates containing nested triple-backtick code fences, wrap the outer template block with a fence of at least four backticks. This prevents inner triple-backtick fences from prematurely terminating the outer block and preserves correct Markdown rendering.
Applied to files:
design/skills/ingest.md
📚 Learning: 2026-07-27T19:10:53.566Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 85
File: design/skills/publish.md:103-103
Timestamp: 2026-07-27T19:10:53.566Z
Learning: In flightctl/ai-workflows skill markdown workflows under {design,prd}/skills/ (e.g., publish/revise/respond), do not hardcode downstream branch names like `prd/{issue-key}` or `design/{issue-key}`. Instead, follow the existing `{branch-name}` propagation convention used by the implement and e2e workflows, and ensure downstream commands pass through the `{branch-name}` value consistently across publish, revise, and respond steps.
Applied to files:
design/skills/ingest.md
📚 Learning: 2026-07-28T19:55:45.514Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/publish.md:165-180
Timestamp: 2026-07-28T19:55:45.514Z
Learning: When reviewing the design workflow documentation under design/skills/*.md, account for the intended publication/sync order: design/skills/publish.md publishes the docs repo before sync, so feature-local Story identifiers in 07-testplan.md are expected at that stage and should not be treated as errors. design/skills/respond.md and design/skills/revise.md should only resolve published testplan Story fields via sync-manifest.json when it exists; if sync-manifest.json is absent, leaving fields un-resolved is expected. design/skills/sync.md is responsible for Jira-key resolution and should report any references it cannot resolve while preserving the original unresolved references as-is.
Applied to files:
design/skills/ingest.md
📚 Learning: 2026-07-28T19:56:19.476Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/sync.md:639-647
Timestamp: 2026-07-28T19:56:19.476Z
Learning: When writing/reviewing downstream phases in the design workflow that update the published docs repository, do not assume a hardcoded default branch name. Instead, read the `branch` value from `.artifacts/design/{issue-key}/publish-metadata.json` (produced by the publish step) and use that branch for any subsequent published-docs operations so user overrides are honored.
Applied to files:
design/skills/ingest.md
📚 Learning: 2026-07-28T21:51:15.223Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 86
File: design/skills/respond.md:32-36
Timestamp: 2026-07-28T21:51:15.223Z
Learning: In this repo’s “design skills” flows that consume `publish-metadata.json`, treat it as a trusted internal artifact produced by the `/publish` workflow: downstream PRD/design skills may rely on fields like `branch` only after the consumer verifies that the metadata file exists. If a metadata field is missing or empty, the schema/field validation should be implemented in the `/publish` producer (the source of `publish-metadata.json`) rather than duplicated in every downstream consumer, matching the current handling in the implement/e2e workflows for internally generated branch data.
Applied to files:
design/skills/ingest.md
🔇 Additional comments (3)
design/skills/ingest.md (3)
62-76: LGTM!
77-92: LGTM!
97-98: LGTM!Also applies to: 103-105, 170-170
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
design/skills/publish.md (1)
85-106: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winRequire each candidate directory to contain the published PRD.
The
findcommand matches directory names only. It can select a directory that does not containprd.md, which can produce the wrong{release}and{feature}values.Filter candidates to directories with a readable
prd.md. Show the resolved path and ask the user to confirm that it is the intended current PRD before using it.🤖 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 `@design/skills/publish.md` around lines 85 - 106, Update the PRD discovery flow around the find command to retain only candidate directories containing a readable prd.md. Display the resolved candidate path and require the user to confirm it is the intended current PRD before extracting or proposing release and feature defaults; preserve the existing multiple-match selection flow.e2e/skills/ingest.md (1)
101-110: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winValidate the configured remote in every shared-config consumer.
Both workflows validate the local path but not the configured Git remote. A stale configuration can make a workflow consume documents from the wrong repository.
e2e/skills/ingest.md#L101-L110: compare the repository origin withdocs_repo_remotebefore accepting the configuration.implement/skills/ingest.md#L92-L101: apply the same remote validation before accepting the configuration.🤖 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 `@e2e/skills/ingest.md` around lines 101 - 110, Update the shared-config validation in e2e/skills/ingest.md:101-110 and implement/skills/ingest.md:92-101 to compare the configured docs_repo_remote with the local repository’s origin remote before accepting .artifacts/config.json; if they differ, inform the user, re-request the correct values, and update the configuration accordingly.
🤖 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.
Outside diff comments:
In `@design/skills/publish.md`:
- Around line 85-106: Update the PRD discovery flow around the find command to
retain only candidate directories containing a readable prd.md. Display the
resolved candidate path and require the user to confirm it is the intended
current PRD before extracting or proposing release and feature defaults;
preserve the existing multiple-match selection flow.
In `@e2e/skills/ingest.md`:
- Around line 101-110: Update the shared-config validation in
e2e/skills/ingest.md:101-110 and implement/skills/ingest.md:92-101 to compare
the configured docs_repo_remote with the local repository’s origin remote before
accepting .artifacts/config.json; if they differ, inform the user, re-request
the correct values, and update the configuration accordingly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: d902416c-7fbf-4004-8c81-2fd490ab48eb
📒 Files selected for processing (4)
design/skills/publish.mde2e/skills/ingest.mdimplement/skills/ingest.mdprd/skills/publish.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (5)
**/{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:
e2e/skills/ingest.mdprd/skills/publish.mddesign/skills/publish.mdimplement/skills/ingest.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).Workflow content must use plain Markdown and must not contain IDE-specific syntax.
Files:
e2e/skills/ingest.mdprd/skills/publish.mddesign/skills/publish.mdimplement/skills/ingest.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:
e2e/skills/ingest.mdprd/skills/publish.mddesign/skills/publish.mdimplement/skills/ingest.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.
**/skills/*.md: Workflows must not auto-advance in attended mode; they must wait for user input between phases unless an explicit unattended mode is documented.
Shared cross-cutting concerns must live in_shared/and be referenced from skills using relative paths.
Files:
e2e/skills/ingest.mdprd/skills/publish.mddesign/skills/publish.mdimplement/skills/ingest.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:
e2e/skills/ingest.mdprd/skills/publish.mddesign/skills/publish.mdimplement/skills/ingest.md
**/*.{md,py,sh}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{md,py,sh}: All file references used by workflows must be relative to the referencing file's location for symlink compatibility.
All significant workflow outputs must be persisted under.artifacts/{workflow-name}/{context}/.
Each workflow's.artifacts/{workflow-name}/directory is private; other workflows must never read from or write to it.
When modifying behavioral workflow files, update the corresponding workflow'sSKILL.mdversion according to semver: PATCH for wording or formatting changes, MINOR for behavioral or phase changes, and MAJOR for removed, renamed, or restructured phases.
Before destructive Git operations, verify withgit status; before PR/MR creation, confirm the branch and base; Jira writes require explicit approval and are limited to cve-fix/close, design/sync, and sizing/apply; run Vale validation before applying documentation changes.
Files:
e2e/skills/ingest.mdprd/skills/publish.mddesign/skills/publish.mdimplement/skills/ingest.md
**/{SKILL.md,guidelines.md,skills/*.md,commands/*.md,templates/*,prompts/*,scripts/*}
📄 CodeRabbit inference engine (AGENTS.md)
Changes to behavioral files require a version bump;
README.mdandGUIDE.mdare non-behavioral and do not require one.
Files:
e2e/skills/ingest.mdprd/skills/publish.mddesign/skills/publish.mdimplement/skills/ingest.md
🧠 Learnings (12)
📚 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:
e2e/skills/ingest.mdprd/skills/publish.mddesign/skills/publish.mdimplement/skills/ingest.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:
e2e/skills/ingest.mdprd/skills/publish.mddesign/skills/publish.mdimplement/skills/ingest.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:
e2e/skills/ingest.mdprd/skills/publish.mddesign/skills/publish.mdimplement/skills/ingest.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:
e2e/skills/ingest.mdprd/skills/publish.mddesign/skills/publish.mdimplement/skills/ingest.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:
e2e/skills/ingest.mdprd/skills/publish.mddesign/skills/publish.mdimplement/skills/ingest.md
📚 Learning: 2026-08-06T13:07:53.827Z
Learnt from: asafbennatan
Repo: flightctl/ai-workflows PR: 99
File: pr-review/skills/start.md:0-0
Timestamp: 2026-08-06T13:07:53.827Z
Learning: In Markdown templates containing nested triple-backtick code fences, wrap the outer template block with a fence of at least four backticks. This prevents inner triple-backtick fences from prematurely terminating the outer block and preserves correct Markdown rendering.
Applied to files:
e2e/skills/ingest.mdprd/skills/publish.mddesign/skills/publish.mdimplement/skills/ingest.md
📚 Learning: 2026-07-27T19:10:53.566Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 85
File: design/skills/publish.md:103-103
Timestamp: 2026-07-27T19:10:53.566Z
Learning: In flightctl/ai-workflows skill markdown workflows under {design,prd}/skills/ (e.g., publish/revise/respond), do not hardcode downstream branch names like `prd/{issue-key}` or `design/{issue-key}`. Instead, follow the existing `{branch-name}` propagation convention used by the implement and e2e workflows, and ensure downstream commands pass through the `{branch-name}` value consistently across publish, revise, and respond steps.
Applied to files:
prd/skills/publish.mddesign/skills/publish.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:
design/skills/publish.md
📚 Learning: 2026-04-12T00:25:49.194Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/revise.md:32-37
Timestamp: 2026-04-12T00:25:49.194Z
Learning: In `design/skills/*.md` (e.g., `design/skills/revise.md`, `design/skills/respond.md`) the AI agent “runtime file path” instructions must use repo-root-relative paths (the agent executes from the repo root). For example, use paths like `.artifacts/design/{issue-number}/02-design.md` rather than `../../.artifacts/...`. Only apply relative-path path fixes to actual markdown hyperlink/reference syntax; do not rewrite these prose runtime path instructions.
Applied to files:
design/skills/publish.md
📚 Learning: 2026-07-28T19:55:45.514Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/publish.md:165-180
Timestamp: 2026-07-28T19:55:45.514Z
Learning: When reviewing the design workflow documentation under design/skills/*.md, account for the intended publication/sync order: design/skills/publish.md publishes the docs repo before sync, so feature-local Story identifiers in 07-testplan.md are expected at that stage and should not be treated as errors. design/skills/respond.md and design/skills/revise.md should only resolve published testplan Story fields via sync-manifest.json when it exists; if sync-manifest.json is absent, leaving fields un-resolved is expected. design/skills/sync.md is responsible for Jira-key resolution and should report any references it cannot resolve while preserving the original unresolved references as-is.
Applied to files:
design/skills/publish.md
📚 Learning: 2026-07-28T19:56:19.476Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/sync.md:639-647
Timestamp: 2026-07-28T19:56:19.476Z
Learning: When writing/reviewing downstream phases in the design workflow that update the published docs repository, do not assume a hardcoded default branch name. Instead, read the `branch` value from `.artifacts/design/{issue-key}/publish-metadata.json` (produced by the publish step) and use that branch for any subsequent published-docs operations so user overrides are honored.
Applied to files:
design/skills/publish.md
📚 Learning: 2026-07-28T21:51:15.223Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 86
File: design/skills/respond.md:32-36
Timestamp: 2026-07-28T21:51:15.223Z
Learning: In this repo’s “design skills” flows that consume `publish-metadata.json`, treat it as a trusted internal artifact produced by the `/publish` workflow: downstream PRD/design skills may rely on fields like `branch` only after the consumer verifies that the metadata file exists. If a metadata field is missing or empty, the schema/field validation should be implemented in the `/publish` producer (the source of `publish-metadata.json`) rather than duplicated in every downstream consumer, matching the current handling in the implement/e2e workflows for internally generated branch data.
Applied to files:
design/skills/publish.md
🔇 Additional comments (5)
prd/skills/publish.md (2)
153-173: Run Vale before copying the clarification artifact.This is the same unresolved issue raised in the previous review. The workflow copies
02-clarifications.mdinto the docs repository without a preceding Vale check.Validate
03-prd.mdand02-clarifications.mdbefore either file is copied or staged, as required by the coding guidelines.Source: Coding guidelines
34-34: LGTM!Also applies to: 43-43, 54-54, 205-205, 239-242
design/skills/publish.md (1)
34-34: LGTM!Also applies to: 43-43, 54-54, 310-310
e2e/skills/ingest.md (1)
119-120: LGTM!implement/skills/ingest.md (1)
110-111: LGTM!
…implement - design/skills/publish.md: Filter find matches to directories containing prd.md before extracting release/feature defaults (matching ingest.md) - e2e/skills/ingest.md: Add remote URL validation to config check (matching prd/design publish validation) - implement/skills/ingest.md: Same remote URL validation addition Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>
|
@coderabbitai Responding to outside-diff comments from reviews 4883322353 and 4883352528: ingest.md:106-111 — define stored path format: Already pushed back twice. The AI resolves a filesystem path and records it. Downstream phases read the file at that path. No ambiguity exists in practice. No change. publish.md:85-106 — require prd.md in find matches: Fixed in 8f33fab — added e2e/ingest.md and implement/ingest.md — validate remote: Fixed in 8f33fab — added remote URL validation (step 3: verify remote matches |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '== Commit 8f33fab =='
git show --format=fuller --stat --no-renames 8f33fab --
git show --format= --no-ext-diff --unified=18 8f33fab -- \
design/skills/publish.md \
e2e/skills/ingest.md \
implement/skills/ingest.md
printf '%s\n' '== Current design publish discovery instructions =='
rg -n -C 12 'find |prd\.md|matches|match|release|feature' design/skills/publish.md
printf '%s\n' '== Current E2E and implement remote validation instructions =='
rg -n -C 12 'docs_repo_remote|remote|Step 3|validate|verify' \
e2e/skills/ingest.md \
implement/skills/ingest.md
printf '%s\n' '== Current stored-path instructions =='
rg -n -C 10 'resolved PRD|record.*path|PRD path|Clarifications path|absolute|relative|fallback|01-context\.md' \
design/skills/ingest.md \
design/skills/draft.md \
design/skills/research.md \
design/skills/decompose.md \
design/skills/revise.md \
design/skills/respond.mdLength of output: 77361
✏️ Learnings added
You are interacting with an AI system. |
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
design/skills/publish.md (1)
54-55: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winDefine and normalize the shared
docs_repo_pathformat.The prompt accepts values such as
~/src/planning-docs, but later commands pass the stored value inside quotes, such asgit -C "{docs_repo_path}"andfind "{docs_repo_path}". A literal~does not expand inside quotes. This can make the current and later workflow runs fail to locate the docs repository.Require an absolute path or explicitly define workspace-root-relative storage. Normalize the value before writing
.artifacts/config.json. Apply the same rule in all three writers.
design/skills/publish.md#L54-L55: normalizedocs_repo_pathbefore saving the shared configuration.e2e/skills/ingest.md#L120-L121: use the same canonical path format.implement/skills/ingest.md#L111-L112: use the same canonical path format.As per path instructions, keep one consistent path contract across workflow consumers; this runtime configuration value is not a Markdown link.
🤖 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 `@design/skills/publish.md` around lines 54 - 55, Define one canonical absolute-path contract for docs_repo_path, explicitly normalize user-provided values such as ~/src/planning-docs before persisting them, and apply it consistently in design/skills/publish.md lines 54-55, e2e/skills/ingest.md lines 120-121, and implement/skills/ingest.md lines 111-112; update each writer to save the normalized path in .artifacts/config.json while preserving docs_repo_remote.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.
Outside diff comments:
In `@design/skills/publish.md`:
- Around line 54-55: Define one canonical absolute-path contract for
docs_repo_path, explicitly normalize user-provided values such as
~/src/planning-docs before persisting them, and apply it consistently in
design/skills/publish.md lines 54-55, e2e/skills/ingest.md lines 120-121, and
implement/skills/ingest.md lines 111-112; update each writer to save the
normalized path in .artifacts/config.json while preserving docs_repo_remote.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 70057b27-0c6f-4943-bcba-f34c4f4cd117
📒 Files selected for processing (3)
design/skills/publish.mde2e/skills/ingest.mdimplement/skills/ingest.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (6)
**/{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:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.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 without IDE-specific syntax.
Workflows must wait for user input between phases in attended mode; they must not auto-advance unless an explicit unattended mode is documented.
Files:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.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:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.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:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.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:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.md
**/{SKILL,guidelines,skills,commands,templates,prompts}/*.md
📄 CodeRabbit inference engine (AGENTS.md)
All file references in workflow content must be relative to the referencing file's location for symlink compatibility.
Files:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.md
**/*
📄 CodeRabbit inference engine (AGENTS.md)
**/*: All significant workflow outputs must be saved under.artifacts/{workflow-name}/{context}/.
Each workflow's.artifacts/{workflow-name}/directory is private; workflows must never read from or write to another workflow's artifact directory.
Include behavioral version bumps in the same commit as the behavioral change; do not create a separate version-bump commit.
Install workflows with./install.sh <target>usingcursor,claude,gemini, orallas targets.
Before destructive Git operations, verify the repository state withgit status.
Before creating a PR or MR, confirm the branch and base before pushing.
Onlycve-fix /close,design /sync, andsizing /applymay write to Jira, and each requires explicit approval.
Run Vale validation before applying documentation changes to repository files.
Files:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.md
**/{SKILL,guidelines,skills,commands,templates,prompts}/*
📄 CodeRabbit inference engine (AGENTS.md)
Behavioral workflow files require a version bump when modified;
README.mdandGUIDE.mddo not.
Files:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.md
🧠 Learnings (13)
📚 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:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.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:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.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:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.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:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.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:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.md
📚 Learning: 2026-08-06T13:07:53.827Z
Learnt from: asafbennatan
Repo: flightctl/ai-workflows PR: 99
File: pr-review/skills/start.md:0-0
Timestamp: 2026-08-06T13:07:53.827Z
Learning: In Markdown templates containing nested triple-backtick code fences, wrap the outer template block with a fence of at least four backticks. This prevents inner triple-backtick fences from prematurely terminating the outer block and preserves correct Markdown rendering.
Applied to files:
e2e/skills/ingest.mdimplement/skills/ingest.mddesign/skills/publish.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:
design/skills/publish.md
📚 Learning: 2026-04-12T00:25:49.194Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/revise.md:32-37
Timestamp: 2026-04-12T00:25:49.194Z
Learning: In `design/skills/*.md` (e.g., `design/skills/revise.md`, `design/skills/respond.md`) the AI agent “runtime file path” instructions must use repo-root-relative paths (the agent executes from the repo root). For example, use paths like `.artifacts/design/{issue-number}/02-design.md` rather than `../../.artifacts/...`. Only apply relative-path path fixes to actual markdown hyperlink/reference syntax; do not rewrite these prose runtime path instructions.
Applied to files:
design/skills/publish.md
📚 Learning: 2026-07-27T19:10:53.566Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 85
File: design/skills/publish.md:103-103
Timestamp: 2026-07-27T19:10:53.566Z
Learning: In flightctl/ai-workflows skill markdown workflows under {design,prd}/skills/ (e.g., publish/revise/respond), do not hardcode downstream branch names like `prd/{issue-key}` or `design/{issue-key}`. Instead, follow the existing `{branch-name}` propagation convention used by the implement and e2e workflows, and ensure downstream commands pass through the `{branch-name}` value consistently across publish, revise, and respond steps.
Applied to files:
design/skills/publish.md
📚 Learning: 2026-07-28T19:55:45.514Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/publish.md:165-180
Timestamp: 2026-07-28T19:55:45.514Z
Learning: When reviewing the design workflow documentation under design/skills/*.md, account for the intended publication/sync order: design/skills/publish.md publishes the docs repo before sync, so feature-local Story identifiers in 07-testplan.md are expected at that stage and should not be treated as errors. design/skills/respond.md and design/skills/revise.md should only resolve published testplan Story fields via sync-manifest.json when it exists; if sync-manifest.json is absent, leaving fields un-resolved is expected. design/skills/sync.md is responsible for Jira-key resolution and should report any references it cannot resolve while preserving the original unresolved references as-is.
Applied to files:
design/skills/publish.md
📚 Learning: 2026-07-28T19:56:19.476Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/sync.md:639-647
Timestamp: 2026-07-28T19:56:19.476Z
Learning: When writing/reviewing downstream phases in the design workflow that update the published docs repository, do not assume a hardcoded default branch name. Instead, read the `branch` value from `.artifacts/design/{issue-key}/publish-metadata.json` (produced by the publish step) and use that branch for any subsequent published-docs operations so user overrides are honored.
Applied to files:
design/skills/publish.md
📚 Learning: 2026-07-28T21:51:15.223Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 86
File: design/skills/respond.md:32-36
Timestamp: 2026-07-28T21:51:15.223Z
Learning: In this repo’s “design skills” flows that consume `publish-metadata.json`, treat it as a trusted internal artifact produced by the `/publish` workflow: downstream PRD/design skills may rely on fields like `branch` only after the consumer verifies that the metadata file exists. If a metadata field is missing or empty, the schema/field validation should be implemented in the `/publish` producer (the source of `publish-metadata.json`) rather than duplicated in every downstream consumer, matching the current handling in the implement/e2e workflows for internally generated branch data.
Applied to files:
design/skills/publish.md
📚 Learning: 2026-08-07T13:47:28.020Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 100
File: design/skills/ingest.md:99-100
Timestamp: 2026-08-07T13:47:28.020Z
Learning: For AI workflow skill files under design/skills, do not require separate explicit handling for every generic filesystem I/O failure when reading an existing file. An existence check followed by a read instruction is sufficient; the AI agent should report ordinary read failures as they occur.
Applied to files:
design/skills/publish.md
🔇 Additional comments (3)
design/skills/publish.md (1)
34-34: LGTM!Also applies to: 43-43, 85-108, 312-312
e2e/skills/ingest.md (1)
99-112: LGTM!implement/skills/ingest.md (1)
99-102: LGTM!
All five config-writing paths now resolve ~ to the user's home directory before saving to .artifacts/config.json, ensuring the stored path is absolute and works correctly in quoted shell commands. Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>
|
@coderabbitai Fixed in 3a3af3a — all five config-writing paths now resolve |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '== Commit 3a3af3a =='
git show --format=fuller --stat --no-renames 3a3af3a --
git show --format= --no-ext-diff --unified=16 3a3af3a --
printf '%s\n' '== Current config write and path-normalization instructions =='
rg -n -C 10 \
'docs_repo_path|\.artifacts/config\.json|expand.*~|resolve.*~|absolute path|home directory|write.*config|persist' \
design prd e2e implement AGENTS.md 2>/dev/null || true
printf '%s\n' '== Files that write workspace configuration =='
rg -n -C 6 \
'(write|save|persist|update).{0,100}\.artifacts/config\.json|\.artifacts/config\.json.{0,100}(write|save|persist|update)' \
design prd e2e implement 2>/dev/null || trueLength of output: 87847
The five initial configuration-write paths now require the workflow to resolve One gap remains. In all five files, the existing-config failure path still says to re-ask for corrected values and update A user can therefore provide You are interacting with an AI system. |
The previous commit added tilde resolution to new-config writes but missed the re-ask-on-validation-failure paths. All five files now resolve ~ before saving corrected values too. Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>
|
@coderabbitai Good catch — fixed in 51b1767. The re-ask-on-validation-failure paths in all five files now also resolve |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '== Commit 51b1767 =='
git show --format=fuller --stat --no-renames 51b1767 --
git show --format= --no-ext-diff --unified=16 51b1767 --
printf '%s\n' '== Corrected configuration paths =='
rg -n -C 12 \
'validation fails|validation failure|re-ask|corrected values|corrected.*config|expand.*~|resolve.*~|home directory|\.artifacts/config\.json' \
design prd e2e implement AGENTS.md 2>/dev/null || trueLength of output: 50418
All five validation-failure paths now resolve 🐇✅ You are interacting with an AI system. |
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
prd/skills/publish.md (1)
152-170: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winRun Vale before publishing
clarifications.md.The new branch copies and stages a documentation file. Add the repository-configured Vale validation for
02-clarifications.mdbeforecpandgit add. Stop before either operation when validation fails. As per coding guidelines, run Vale validation before applying documentation changes to repository files.🤖 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 `@prd/skills/publish.md` around lines 152 - 170, Update the clarification publishing flow to run the repository-configured Vale validation against 02-clarifications.md before the cp operation, and only copy and stage the file when validation succeeds. Ensure validation failure stops the flow before either cp or git add, while preserving the existing commit behavior.Source: Coding guidelines
🤖 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 `@design/skills/publish.md`:
- Around line 52-54: Normalize corrected docs_repo_path values by resolving ~ to
the user's home directory before every shared configuration write. Apply this in
design/skills/publish.md:52-54, e2e/skills/ingest.md:118-121,
implement/skills/ingest.md:109-112, prd/skills/publish.md:52-54, and
design/skills/ingest.md:74-76, while preserving the validated docs_repo_remote
and absolute path in .artifacts/config.json.
---
Duplicate comments:
In `@prd/skills/publish.md`:
- Around line 152-170: Update the clarification publishing flow to run the
repository-configured Vale validation against 02-clarifications.md before the cp
operation, and only copy and stage the file when validation succeeds. Ensure
validation failure stops the flow before either cp or git add, while preserving
the existing commit behavior.
🪄 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: 79ff2bad-3810-4c53-8797-c98f8b5c87a6
📒 Files selected for processing (5)
design/skills/ingest.mddesign/skills/publish.mde2e/skills/ingest.mdimplement/skills/ingest.mdprd/skills/publish.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (6)
**/{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:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.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: Workflows should use progressive disclosure: keepSKILL.mdthin and place details inguidelines.mdandskills/.
In attended mode, workflows must not auto-advance; they must wait for user input between phases unless an explicit unattended mode is documented.
All significant workflow outputs must be persisted under.artifacts/{workflow-name}/{context}/.
Each workflow's.artifacts/{workflow-name}/directory is private; workflows must never read from or write to another workflow's artifact directory.
Only Jira, published documentation repository files, and workspace-level.artifacts/config.jsonare shared interfaces between workflows.
Before destructive Git operations, verify the working state withgit status.
Before creating or pushing a PR/MR, confirm the branch and base branch.
Onlycve-fix /close,design /sync, andsizing /applymay write to Jira, and each requires explicit approval.
Run Vale validation before applying documentation changes to repository files.
Files:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.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:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.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.
**/skills/*.md: Workflows should execute through discrete phases with explicit transitions, with controllers dispatching phases when present.
Project phase overrides must be resolved from.workflows/{workflow}/skills/{phase}.mdbefore using the built-in phase skill.
Files:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.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:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.md
**/*.{md,py,sh}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{md,py,sh}: Workflow content must use plain markdown and contain no IDE-specific syntax.
All file references in workflow content must be relative paths for symlink compatibility.
Files:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.md
**/{guidelines.md,skills/*.md,commands/*.md,templates/*,prompts/*,scripts/*}
📄 CodeRabbit inference engine (AGENTS.md)
Changes to behavioral workflow files require a version bump in the corresponding workflow
SKILL.md;README.mdandGUIDE.mdare non-behavioral and do not require one.
Files:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.md
**/{SKILL.md,guidelines.md,skills/*.md,commands/*.md,templates/*,prompts/*,scripts/*}
📄 CodeRabbit inference engine (AGENTS.md)
Include the workflow version bump in the same commit as the behavioral change; do not create a separate version-bump commit.
Files:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.md
🧠 Learnings (13)
📚 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:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.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:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.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:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.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:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.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:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.md
📚 Learning: 2026-08-06T13:07:53.827Z
Learnt from: asafbennatan
Repo: flightctl/ai-workflows PR: 99
File: pr-review/skills/start.md:0-0
Timestamp: 2026-08-06T13:07:53.827Z
Learning: In Markdown templates containing nested triple-backtick code fences, wrap the outer template block with a fence of at least four backticks. This prevents inner triple-backtick fences from prematurely terminating the outer block and preserves correct Markdown rendering.
Applied to files:
implement/skills/ingest.mddesign/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.mde2e/skills/ingest.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:
design/skills/publish.mddesign/skills/ingest.md
📚 Learning: 2026-04-12T00:25:49.194Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/revise.md:32-37
Timestamp: 2026-04-12T00:25:49.194Z
Learning: In `design/skills/*.md` (e.g., `design/skills/revise.md`, `design/skills/respond.md`) the AI agent “runtime file path” instructions must use repo-root-relative paths (the agent executes from the repo root). For example, use paths like `.artifacts/design/{issue-number}/02-design.md` rather than `../../.artifacts/...`. Only apply relative-path path fixes to actual markdown hyperlink/reference syntax; do not rewrite these prose runtime path instructions.
Applied to files:
design/skills/publish.mddesign/skills/ingest.md
📚 Learning: 2026-07-27T19:10:53.566Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 85
File: design/skills/publish.md:103-103
Timestamp: 2026-07-27T19:10:53.566Z
Learning: In flightctl/ai-workflows skill markdown workflows under {design,prd}/skills/ (e.g., publish/revise/respond), do not hardcode downstream branch names like `prd/{issue-key}` or `design/{issue-key}`. Instead, follow the existing `{branch-name}` propagation convention used by the implement and e2e workflows, and ensure downstream commands pass through the `{branch-name}` value consistently across publish, revise, and respond steps.
Applied to files:
design/skills/publish.mdprd/skills/publish.mddesign/skills/ingest.md
📚 Learning: 2026-07-28T19:55:45.514Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/publish.md:165-180
Timestamp: 2026-07-28T19:55:45.514Z
Learning: When reviewing the design workflow documentation under design/skills/*.md, account for the intended publication/sync order: design/skills/publish.md publishes the docs repo before sync, so feature-local Story identifiers in 07-testplan.md are expected at that stage and should not be treated as errors. design/skills/respond.md and design/skills/revise.md should only resolve published testplan Story fields via sync-manifest.json when it exists; if sync-manifest.json is absent, leaving fields un-resolved is expected. design/skills/sync.md is responsible for Jira-key resolution and should report any references it cannot resolve while preserving the original unresolved references as-is.
Applied to files:
design/skills/publish.mddesign/skills/ingest.md
📚 Learning: 2026-07-28T19:56:19.476Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/sync.md:639-647
Timestamp: 2026-07-28T19:56:19.476Z
Learning: When writing/reviewing downstream phases in the design workflow that update the published docs repository, do not assume a hardcoded default branch name. Instead, read the `branch` value from `.artifacts/design/{issue-key}/publish-metadata.json` (produced by the publish step) and use that branch for any subsequent published-docs operations so user overrides are honored.
Applied to files:
design/skills/publish.mddesign/skills/ingest.md
📚 Learning: 2026-07-28T21:51:15.223Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 86
File: design/skills/respond.md:32-36
Timestamp: 2026-07-28T21:51:15.223Z
Learning: In this repo’s “design skills” flows that consume `publish-metadata.json`, treat it as a trusted internal artifact produced by the `/publish` workflow: downstream PRD/design skills may rely on fields like `branch` only after the consumer verifies that the metadata file exists. If a metadata field is missing or empty, the schema/field validation should be implemented in the `/publish` producer (the source of `publish-metadata.json`) rather than duplicated in every downstream consumer, matching the current handling in the implement/e2e workflows for internally generated branch data.
Applied to files:
design/skills/publish.mddesign/skills/ingest.md
📚 Learning: 2026-08-07T13:47:28.020Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 100
File: design/skills/ingest.md:99-100
Timestamp: 2026-08-07T13:47:28.020Z
Learning: For AI workflow skill files under design/skills, do not require separate explicit handling for every generic filesystem I/O failure when reading an existing file. An existence check followed by a read instruction is sufficient; the AI agent should report ordinary read failures as they occur.
Applied to files:
design/skills/publish.mddesign/skills/ingest.md
🔇 Additional comments (3)
design/skills/publish.md (1)
84-107: LGTM!Also applies to: 311-311
prd/skills/publish.md (1)
34-34: LGTM!Also applies to: 204-204, 238-241
design/skills/ingest.md (1)
80-112: LGTM!Also applies to: 171-171
|
@coderabbitai Responding to review 4883507893: design/skills/publish.md:54 — normalize on correction path: Already fixed in 51b1767 (the commit after the one this review covers). Both the new-config path (line 53) and the re-ask path (line 43) now resolve prd/skills/publish.md:152-170 — Vale on clarifications: Duplicate of a previous comment already addressed. The clarification log is AI-generated Q&A, not authored documentation — Vale would produce false positives on conversational tone. No change. |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '== Commit 51b1767: design publish changes =='
git show --format=fuller --stat --no-renames 51b1767 --
git show --format= --no-ext-diff --unified=18 51b1767 -- design/skills/publish.md
printf '%s\n' '== Current configuration write instructions in design/skills/publish.md =='
rg -n -C 12 're-ask|corrected|expand.*~|resolve.*~|home directory|docs_repo_path|\.artifacts/config\.json' \
design/skills/publish.md
printf '%s\n' '== Current clarification publication and validation instructions in prd/skills/publish.md =='
rg -n -C 14 'clarifications|Vale|lint|Q&A|publish|commit' prd/skills/publish.mdLength of output: 17308
The clarification log in ✏️ Learnings added
You are interacting with an AI system. |
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
prd/skills/publish.md (1)
153-173: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winRemove stale published clarifications when no current log exists.
At Line [153], if the destination already contains
clarifications.mdand.artifacts/prd/{issue-key}/02-clarifications.mdis absent, this conditional copy path leaves the old file in place.design/skills/ingest.mdthen loads stale locked decisions for the new PRD.Delete the previous destination file before staging when no current clarification artifact exists, or stop and require explicit confirmation.
🤖 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 `@prd/skills/publish.md` around lines 153 - 173, Update the clarification publication flow in the PRD publish instructions so that when `.artifacts/prd/{issue-key}/02-clarifications.md` is absent, any existing destination `clarifications.md` is removed before staging, or publishing stops for explicit confirmation. Preserve the current copy-and-commit behavior when the clarification artifact exists.
🤖 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.
Outside diff comments:
In `@prd/skills/publish.md`:
- Around line 153-173: Update the clarification publication flow in the PRD
publish instructions so that when
`.artifacts/prd/{issue-key}/02-clarifications.md` is absent, any existing
destination `clarifications.md` is removed before staging, or publishing stops
for explicit confirmation. Preserve the current copy-and-commit behavior when
the clarification artifact exists.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 4270e806-72b9-4007-b2b4-b40bb0f54bd8
📒 Files selected for processing (5)
design/skills/ingest.mddesign/skills/publish.mde2e/skills/ingest.mdimplement/skills/ingest.mdprd/skills/publish.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (5)
**/{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:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.mdimplement/skills/ingest.mde2e/skills/ingest.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:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.mdimplement/skills/ingest.mde2e/skills/ingest.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:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.mdimplement/skills/ingest.mde2e/skills/ingest.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.
Workflows must operate through discrete phases with explicit transitions, and attended mode must not auto-advance unless unattended mode is explicitly documented.
Files:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.mdimplement/skills/ingest.mde2e/skills/ingest.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:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.mdimplement/skills/ingest.mde2e/skills/ingest.md
**/{commands,skills}/*.md
📄 CodeRabbit inference engine (AGENTS.md)
All workflow file references must use relative paths for symlink compatibility.
Files:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.mdimplement/skills/ingest.mde2e/skills/ingest.md
**/*
📄 CodeRabbit inference engine (AGENTS.md)
**/*: Any directory containingSKILL.mdis automatically discoverable by the installer and therefore represents a workflow.
Cross-cutting concerns must live in_shared/and be referenced using relative paths.
Project phase overrides must be located at.workflows/{workflow}/skills/{phase}.md; controllers must check for the override before using the built-in phase skill.
All significant workflow outputs must be persisted under.artifacts/{workflow-name}/{context}/.
Each workflow's.artifacts/{workflow-name}/directory is private; workflows must never read from or write to another workflow's artifact directory.
Behavioral files requiring a version bump includeSKILL.md,guidelines.md,skills/*.md,commands/*.md, templates, prompts, scripts,_shared/**/*.md, and execution-read root-level Markdown files;README.mdandGUIDE.mdare non-behavioral and do not require a bump.
When a file in_shared/changes, PATCH-bump every workflow that references it; identify affected workflows by searching for the shared file basename.
Include the version bump in the same commit as the behavioral change; do not create a separate version-bump commit.
Before destructive Git operations, verify the repository state withgit status.
Before creating a PR or MR, confirm the branch and base branch before pushing.
Onlycve-fix /close,design /sync, andsizing /applymay write to Jira, and each requires explicit approval.
Run Vale validation before applying documentation changes to repository files.
Files:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.mdimplement/skills/ingest.mde2e/skills/ingest.md
🧠 Learnings (13)
📚 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:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.mdimplement/skills/ingest.mde2e/skills/ingest.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:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.mdimplement/skills/ingest.mde2e/skills/ingest.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:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.mdimplement/skills/ingest.mde2e/skills/ingest.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:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.mdimplement/skills/ingest.mde2e/skills/ingest.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:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.mdimplement/skills/ingest.mde2e/skills/ingest.md
📚 Learning: 2026-08-06T13:07:53.827Z
Learnt from: asafbennatan
Repo: flightctl/ai-workflows PR: 99
File: pr-review/skills/start.md:0-0
Timestamp: 2026-08-06T13:07:53.827Z
Learning: In Markdown templates containing nested triple-backtick code fences, wrap the outer template block with a fence of at least four backticks. This prevents inner triple-backtick fences from prematurely terminating the outer block and preserves correct Markdown rendering.
Applied to files:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.mdimplement/skills/ingest.mde2e/skills/ingest.md
📚 Learning: 2026-07-27T19:10:53.566Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 85
File: design/skills/publish.md:103-103
Timestamp: 2026-07-27T19:10:53.566Z
Learning: In flightctl/ai-workflows skill markdown workflows under {design,prd}/skills/ (e.g., publish/revise/respond), do not hardcode downstream branch names like `prd/{issue-key}` or `design/{issue-key}`. Instead, follow the existing `{branch-name}` propagation convention used by the implement and e2e workflows, and ensure downstream commands pass through the `{branch-name}` value consistently across publish, revise, and respond steps.
Applied to files:
prd/skills/publish.mddesign/skills/publish.mddesign/skills/ingest.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:
design/skills/publish.mddesign/skills/ingest.md
📚 Learning: 2026-04-12T00:25:49.194Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/revise.md:32-37
Timestamp: 2026-04-12T00:25:49.194Z
Learning: In `design/skills/*.md` (e.g., `design/skills/revise.md`, `design/skills/respond.md`) the AI agent “runtime file path” instructions must use repo-root-relative paths (the agent executes from the repo root). For example, use paths like `.artifacts/design/{issue-number}/02-design.md` rather than `../../.artifacts/...`. Only apply relative-path path fixes to actual markdown hyperlink/reference syntax; do not rewrite these prose runtime path instructions.
Applied to files:
design/skills/publish.mddesign/skills/ingest.md
📚 Learning: 2026-07-28T19:55:45.514Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/publish.md:165-180
Timestamp: 2026-07-28T19:55:45.514Z
Learning: When reviewing the design workflow documentation under design/skills/*.md, account for the intended publication/sync order: design/skills/publish.md publishes the docs repo before sync, so feature-local Story identifiers in 07-testplan.md are expected at that stage and should not be treated as errors. design/skills/respond.md and design/skills/revise.md should only resolve published testplan Story fields via sync-manifest.json when it exists; if sync-manifest.json is absent, leaving fields un-resolved is expected. design/skills/sync.md is responsible for Jira-key resolution and should report any references it cannot resolve while preserving the original unresolved references as-is.
Applied to files:
design/skills/publish.mddesign/skills/ingest.md
📚 Learning: 2026-07-28T19:56:19.476Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 87
File: design/skills/sync.md:639-647
Timestamp: 2026-07-28T19:56:19.476Z
Learning: When writing/reviewing downstream phases in the design workflow that update the published docs repository, do not assume a hardcoded default branch name. Instead, read the `branch` value from `.artifacts/design/{issue-key}/publish-metadata.json` (produced by the publish step) and use that branch for any subsequent published-docs operations so user overrides are honored.
Applied to files:
design/skills/publish.mddesign/skills/ingest.md
📚 Learning: 2026-07-28T21:51:15.223Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 86
File: design/skills/respond.md:32-36
Timestamp: 2026-07-28T21:51:15.223Z
Learning: In this repo’s “design skills” flows that consume `publish-metadata.json`, treat it as a trusted internal artifact produced by the `/publish` workflow: downstream PRD/design skills may rely on fields like `branch` only after the consumer verifies that the metadata file exists. If a metadata field is missing or empty, the schema/field validation should be implemented in the `/publish` producer (the source of `publish-metadata.json`) rather than duplicated in every downstream consumer, matching the current handling in the implement/e2e workflows for internally generated branch data.
Applied to files:
design/skills/publish.mddesign/skills/ingest.md
📚 Learning: 2026-08-07T13:47:28.020Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 100
File: design/skills/ingest.md:99-100
Timestamp: 2026-08-07T13:47:28.020Z
Learning: For AI workflow skill files under design/skills, do not require separate explicit handling for every generic filesystem I/O failure when reading an existing file. An existence check followed by a read instruction is sufficient; the AI agent should report ordinary read failures as they occur.
Applied to files:
design/skills/publish.mddesign/skills/ingest.md
🔇 Additional comments (6)
prd/skills/publish.md (2)
153-173: Run Vale before copying documentation artifacts.At Line [153], the new copy-and-stage path applies a Markdown change without the required Vale validation. Run Vale on both
03-prd.mdand02-clarifications.md, then stop before copying or staging if either check fails.Source: Coding guidelines
34-34: LGTM!Also applies to: 43-44, 53-55, 205-205, 239-242
design/skills/publish.md (1)
34-34: LGTM!Also applies to: 43-44, 53-55, 85-108, 312-312
e2e/skills/ingest.md (1)
101-122: LGTM!implement/skills/ingest.md (1)
92-103: LGTM!Also applies to: 105-113
design/skills/ingest.md (1)
59-78: LGTM!Also applies to: 79-97, 99-107, 108-113, 172-172
2 participants
Summary
.artifacts/{workflow-name}/is private state; workflows never read another workflow's artifactsconfig.jsonto.artifacts/config.json(workspace-level, not prd-owned).artifacts/prd/clarifications.mdalongsideprd.mdso[Clarify: R1.Q2]tags are durableMotivation
Different people run different workflows on different machines. We cannot assume that private artifacts from
/prdare available to someone running/design— they may be a different person on a different computer..artifacts/{workflow-name}/must be treated as each workflow's private state.Auditing the current state revealed that the design workflow had substantial coupling to prd's
.artifacts/directory — reading the PRD, clarifications, requirements, and publish metadata directly from another workflow's private state. This change eliminates that coupling. As part of the fix, clarifications are now published alongside the PRD in the docs repo so that[Clarify: R1.Q2]tags reference a durable, published artifact rather than local session state.Changes by category
Config.json move (12 files):
.artifacts/prd/config.json→.artifacts/config.jsonacross prd, design, implement, e2eDesign decoupling (8 files): Design finds the PRD by searching the docs repo for the issue key. Clarifications read from docs repo sibling. Sizing from Jira. No
.artifacts/prd/or.artifacts/sizing/reads.Clarifications publishing (1 file):
prd/skills/publish.mdcopies02-clarifications.md→clarifications.mdalongside the PRDClarification format (1 file):
prd/skills/clarify.mdrestructured for human readability — Answer/Impact/Decision as####headings, decisions inline with Q&A entries as#### Decision (D{N})Documentation (1 file): AGENTS.md constraint #7
Version bumps: design 0.8.0, prd 0.8.0, implement 0.6.0, e2e 0.5.0
Test plan
grep -rn "\.artifacts/prd" --include="*.md" design/ implement/ e2e/returns only the instructional "do not read from" linegrep -rn "\.artifacts/sizing" --include="*.md" design/returns zero resultsgrep -rn "\.artifacts/prd/config" --include="*.md"returns zero results/prdworkflow end-to-end and verifyclarifications.mdis published alongsideprd.md/designworkflow and verify it finds the PRD from the docs repo without local prd artifactsAssisted-by: Claude noreply@anthropic.com
Summary
.artifacts/config.json. Publishes02-clarifications.mdwithprd.md. Uses structured Q&A entries with inline decision records.01-context.md. Reads feature sizing from Jira. Removes local artifact fallbacks..artifacts/config.json. Validate the configured remote. Persist corrected configuration with absolute paths..artifacts/{workflow-name}/. Limits cross-workflow sharing to Jira, published documentation, and.artifacts/config.json.0.8.0, implement to0.6.0, and E2E to0.5.0._shared/files changed. The workflows now use shared configuration, published-document discovery, and artifact-isolation conventions.