Enforce user-facing focus in PRD workflow (v0.3.0)#68
Conversation
avishayt
requested review from
adalton,
amir-yogev-gh and
eranco74
and removed request for
adalton
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughThe PRD workflow docs and templates were updated to frame requirements around user-visible capabilities, outcomes, and verifiable completion. They also add limits against implementation detail, expand clarification and self-review guidance, and bump the workflow version. ChangesUser-facing PRD guidance
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 12✅ Passed checks (12 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@prd/templates/section-guidance.md`:
- Around line 73-87: Update the acceptance-criteria guidance in
section-guidance.md to allow API responses as valid user-observable evidence for
API-only features, while still forbidding internal state and database checks.
Adjust the wording in the “Acceptance Criteria” section so it no longer says
criteria should not require inspecting API responses; instead, clarify that
acceptance criteria may use user-visible API responses when that is the only
observable proof. Reference the “4. Acceptance Criteria” bullets and keep the
rest of the guidance about independently verifiable checkboxes and primary use
cases intact.
- Around line 25-27: The “Cover all user interfaces” guidance is too absolute
and can force invented UI/CLI coverage for API-only capabilities. Update the
wording in the section guidance so it only requires UI/CLI mentions when those
interfaces actually exist or have been confirmed during clarification, and keep
the emphasis on listing UI/CLI first only when applicable. Use the “Cover all
user interfaces” bullet to make this condition explicit without changing the
“User-facing focus” or “Diagrams” guidance.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 51b97365-9e9a-4c1b-a4e6-f26ef2ed7d28
📒 Files selected for processing (7)
prd/GUIDE.mdprd/SKILL.mdprd/guidelines.mdprd/skills/clarify.mdprd/skills/draft.mdprd/templates/prd.mdprd/templates/section-guidance.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (11)
**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
**/*.md: All file references within workflow files must use relative paths (not absolute) for symlink compatibility across installation scopes
Use plain markdown syntax only—no IDE-specific syntax (no Cursor instructions, Claude directives, or Gemini-specific markup)
Behavioral files (SKILL.md body, guidelines.md, skills/.md, commands/.md, templates/, prompts/, scripts/, and _shared/**/.md) require a version bump on modification; non-behavioral files like README.md and GUIDE.md do notFor 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/GUIDE.mdprd/guidelines.mdprd/SKILL.mdprd/templates/prd.mdprd/skills/clarify.mdprd/skills/draft.mdprd/templates/section-guidance.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/GUIDE.mdprd/guidelines.mdprd/SKILL.mdprd/templates/prd.mdprd/skills/clarify.mdprd/skills/draft.mdprd/templates/section-guidance.md
**
⚙️ CodeRabbit configuration file
**: # AGENTS.mdThis file provides guidance to AI coding assistants when working with this repository.
Project Overview
This repository contains reusable AI coding workflows that can be installed globally or per-project in any environment (Cursor, Claude Code, Gemini). Each workflow is a self-contained directory with structured markdown files that AI agents can read and execute.
Current workflows:
- ai-ready — Codebase scanning and AGENTS.md generation (update)
- bugfix — Systematic bug resolution (assess, reproduce, diagnose, fix, test, review, document, pr)
- code-review — AI-driven code review with human-in-the-loop decisions (start, continue, clean)
- cve-fix — Automated CVE remediation from Jira tickets (start, scan, patch, validate, pr, backport, close)
- design — Design-and-decompose workflow (ingest, research, draft, decompose, revise, publish, respond, sync)
- docs-writer — Documentation creation workflow (gather, plan, draft, validate, apply, mr)
- e2e — Story-to-tests workflow for [QE] stories (ingest, plan, revise, code, validate, publish, respond)
- implement — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond)
- kcs — KCS Solution article workflow (gather, draft, validate, handoff)
- prd — Requirements-to-PRD workflow (ingest, clarify, draft, revise, publish, respond)
- sizing — Pre-cycle Feature sizing with T-shirt sizes and team effort breakdowns (ingest, assess, apply)
- skill-reviewer — Meta-workflow that audits AI skill directories
- triage — Bulk Jira bug triage with AI-driven categorization and HTML reports
Architecture
Workflow Structure
Every workflow follows this canonical structure:
workflow-name/ SKILL.md # Entry point with YAML frontmatter (name, version, description) guidelines.md # Behavioral rules: principles, hard limits, safety, quality README.md # Human-readable documentation (prerequ...
Files:
prd/GUIDE.mdprd/guidelines.mdprd/SKILL.mdprd/templates/prd.mdprd/skills/clarify.mdprd/skills/draft.mdprd/templates/section-guidance.md
*/guidelines.md
📄 CodeRabbit inference engine (AGENTS.md)
Every workflow must include a guidelines.md file containing behavioral rules: principles, hard limits, safety, and quality constraints
Files:
prd/guidelines.md
**/{SKILL.md,guidelines.md,skills/*.md,commands/*.md}
📄 CodeRabbit inference engine (Custom checks)
Flag any absolute filesystem path in markdown files within workflow directories (*/SKILL.md, /skills/.md, /commands/.md, */guidelines.md). Paths like /home/, /Users/, /tmp/, /var/, /opt/ are prohibited because workflows are installed via symlink and must use relative paths only. Paths inside fenced code blocks that are clearly examples (containing "example", "e.g.", or placeholder usernames like /home/user/) are exempt.
Files:
prd/guidelines.mdprd/SKILL.mdprd/skills/clarify.mdprd/skills/draft.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:
prd/guidelines.mdprd/SKILL.md
**/guidelines.md
⚙️ CodeRabbit configuration file
**/guidelines.md: Guidelines review (ai-workflows conventions):
- Must contain: Principles, Hard Limits, Safety, Quality, and
Escalation sections (or equivalent coverage)- Content must NOT duplicate SKILL.md or controller.md — each
file has a distinct role- Escalation criteria must be specific and actionable (not vague
"when things go wrong")- Hard limits must be concrete prohibitions, not suggestions
- All phase references should use consistent naming matching
the workflow's actual phase names
Files:
prd/guidelines.md
*/SKILL.md
📄 CodeRabbit inference engine (AGENTS.md)
*/SKILL.md: Every workflow directory must include a SKILL.md entry point with YAML frontmatter (name, version, description) that stays under 30 lines
When modifying workflow SKILL.md files, update the version in the frontmatter using semver: PATCH for typo/wording fixes, MINOR for step/rule changes, MAJOR for phase/command restructuring
When modifying shared files in _shared/, apply a PATCH-bump to every workflow's SKILL.md that references the modified shared file
Files:
prd/SKILL.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.
Files:
prd/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:
prd/SKILL.md
**/{templates,prompts}/*.md
⚙️ CodeRabbit configuration file
**/{templates,prompts}/*.md: Template/prompt review (ai-workflows conventions):
- Templates use {placeholder} syntax for caller-filled values —
verify all placeholders are documented- Prompt templates must be self-contained: the sub-agent receives
only the prompt, not the caller's context- Prompts must instruct output to .artifacts/, not inline return
- Templates must work when the workflow is installed via symlink
- No absolute paths in templates
Files:
prd/templates/prd.mdprd/templates/section-guidance.md
*/skills/*.md
📄 CodeRabbit inference engine (AGENTS.md)
*/skills/*.md: Workflows must not auto-advance phases in attended mode; they must wait for explicit user input between phases unless an unattended mode is explicitly documented
All significant workflow outputs must be persisted to .artifacts/{workflow-name}/{context}/ directory
Files:
prd/skills/clarify.mdprd/skills/draft.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:
prd/skills/clarify.mdprd/skills/draft.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/clarify.mdprd/skills/draft.md
🧠 Learnings (5)
📚 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:
prd/SKILL.md
📚 Learning: 2026-04-12T00:25:51.234Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/respond.md:29-31
Timestamp: 2026-04-12T00:25:51.234Z
Learning: In flightctl/ai-workflows skill markdown files, treat path references as two categories:
1) For cross-document markdown links (e.g., links to other .md files like ../skills/controller.md or ../../templates/design.md), use paths relative to the current markdown file’s location so links work under symlinks.
2) For runtime artifact paths used as prose instructions to the AI agent (e.g., .artifacts/design/{issue-number}/publish-metadata.json or .artifacts/prd/config.json), keep them repo-root-relative (start with .artifacts/). Do not convert these artifact paths to be relative to the skill file directory (e.g., don’t rewrite to ../../.artifacts/...), because the AI resolves them from the repo root.
Applied to files:
prd/skills/clarify.mdprd/skills/draft.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/clarify.mdprd/skills/draft.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/clarify.mdprd/skills/draft.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/clarify.mdprd/skills/draft.md
🔇 Additional comments (7)
prd/GUIDE.md (1)
11-12: LGTM!prd/guidelines.md (1)
20-20: LGTM!Also applies to: 36-37
prd/templates/section-guidance.md (1)
63-64: LGTM!prd/SKILL.md (1)
3-3: LGTM!prd/skills/clarify.md (1)
45-63: LGTM!prd/skills/draft.md (1)
8-20: LGTM!Also applies to: 75-75, 190-191
prd/templates/prd.md (1)
34-35: LGTM!Also applies to: 38-38, 42-42
PRDs were drifting into design territory — describing API fields, internal architecture, and non-user-observable behavior instead of user capabilities and outcomes. This adds guardrails at every phase to keep PRDs focused on what users can do, see, and experience, and ensures UI/CLI are mentioned alongside the API. Assisted-by: Claude
avishayt
force-pushed
the
prd-user-facing-focus
branch
from
1a414d7 to
a276572
Compare
…evidence Make "Cover all user interfaces" conditional — only mention UI/CLI when they actually exist, rather than assuming they always do. Allow API responses as valid user-observable evidence in acceptance criteria when the API is the user's interface. Assisted-by: Claude
There was a problem hiding this comment.
♻️ Duplicate comments (3)
prd/templates/section-guidance.md (2)
76-81: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winAllow API responses as user-visible evidence.
The acceptance-criteria rule still blocks the only observable proof for API-only features. Keep the ban on internal state/database checks, but let API responses/status codes count when the API is the exposed interface. Based on the earlier review note about API responses.
♻️ Proposed fix
- Do not include criteria that require inspecting internal state, database records, or API responses — those belong in a test plan or design document. + Do not include criteria that require inspecting internal state or database records. If the API is the exposed interface, API responses/status codes may be used as user-observable evidence.🤖 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/templates/section-guidance.md` around lines 76 - 81, The Acceptance Criteria guidance is too restrictive for API-only features in section-guidance.md; update the rule in the Acceptance Criteria block so it still forbids internal state/database checks but explicitly allows API responses and status codes as valid user-visible evidence when the API is the exposed interface. Adjust the wording around the acceptance-criteria checklist in the Acceptance Criteria section to reflect this exception without loosening the rest of the guidance.
25-27: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winMake the interface rule conditional.
This still forces UI/CLI coverage for API-only capabilities. Keep it scoped to interfaces that actually exist or were confirmed in clarification. Based on the earlier API-only review note.
♻️ Proposed fix
- **Cover all user interfaces.** Requirements should mention the UI and CLI alongside the API — not just the API. For example, "Users can create a device via the console, CLI, or API" not just "Users can create a device via the API." When the source material only mentions the API, ask during clarification which other interfaces expose the capability, and list UI and CLI first. + **Cover all user interfaces.** Requirements should mention whichever interfaces actually expose the capability (UI, CLI, API). If the source material only mentions the API, ask during clarification whether UI/CLI also exist before adding them.🤖 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/templates/section-guidance.md` around lines 25 - 27, The “Cover all user interfaces” guidance is too absolute and still implies UI/CLI coverage for API-only capabilities. Update the wording in the section guidance so it explicitly applies only to interfaces that exist or were confirmed during clarification, and keep the example and instruction aligned with that conditional scope. Use the “Cover all user interfaces” bullet and its API example to make the requirement read as interface-aware rather than mandatory for every PRD item.prd/skills/clarify.md (1)
59-63: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winKeep the interface question conditional.
As written, this still pushes UI/CLI into API-only capabilities and will generate the wrong clarification questions. Ask whether other interfaces actually exist, and only mention UI/CLI when they do or when clarification confirms them.
♻️ Proposed fix
- **Cover all interfaces.** When the source material describes a capability only in terms of the API, ask which other interfaces (UI, CLI) also expose it. PRD requirements should mention the UI and CLI first, with the API as an additional option — not default to API-only. + **Cover all interfaces.** When the source material describes a capability only in terms of the API, ask whether any other interfaces actually expose it. Only mention UI/CLI when they exist or are confirmed in clarification.🤖 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/clarify.md` around lines 59 - 63, The clarification guidance in the interface coverage section is too prescriptive and can incorrectly force UI/CLI into API-only capabilities. Update the wording around the relevant guidance in clarify.md so it first asks whether other interfaces actually exist, and only mentions UI or CLI when the source material confirms them or when clarification establishes their presence. Keep the logic conditional in the section that discusses interface-specific questions so it does not default to UI/CLI wording for API-only cases.
🤖 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.
Duplicate comments:
In `@prd/skills/clarify.md`:
- Around line 59-63: The clarification guidance in the interface coverage
section is too prescriptive and can incorrectly force UI/CLI into API-only
capabilities. Update the wording around the relevant guidance in clarify.md so
it first asks whether other interfaces actually exist, and only mentions UI or
CLI when the source material confirms them or when clarification establishes
their presence. Keep the logic conditional in the section that discusses
interface-specific questions so it does not default to UI/CLI wording for
API-only cases.
In `@prd/templates/section-guidance.md`:
- Around line 76-81: The Acceptance Criteria guidance is too restrictive for
API-only features in section-guidance.md; update the rule in the Acceptance
Criteria block so it still forbids internal state/database checks but explicitly
allows API responses and status codes as valid user-visible evidence when the
API is the exposed interface. Adjust the wording around the acceptance-criteria
checklist in the Acceptance Criteria section to reflect this exception without
loosening the rest of the guidance.
- Around line 25-27: The “Cover all user interfaces” guidance is too absolute
and still implies UI/CLI coverage for API-only capabilities. Update the wording
in the section guidance so it explicitly applies only to interfaces that exist
or were confirmed during clarification, and keep the example and instruction
aligned with that conditional scope. Use the “Cover all user interfaces” bullet
and its API example to make the requirement read as interface-aware rather than
mandatory for every PRD item.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: b9932e0a-37fc-4790-8245-50eb887035ff
📒 Files selected for processing (7)
prd/GUIDE.mdprd/SKILL.mdprd/guidelines.mdprd/skills/clarify.mdprd/skills/draft.mdprd/templates/prd.mdprd/templates/section-guidance.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (11)
*/SKILL.md
📄 CodeRabbit inference engine (AGENTS.md)
*/SKILL.md: Every workflow directory must include a SKILL.md entry point with YAML frontmatter (name, version, description) that stays under 30 lines
When modifying workflow SKILL.md files, update the version in the frontmatter using semver: PATCH for typo/wording fixes, MINOR for step/rule changes, MAJOR for phase/command restructuring
When modifying shared files in _shared/, apply a PATCH-bump to every workflow's SKILL.md that references the modified shared file
Files:
prd/SKILL.md
**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
**/*.md: All file references within workflow files must use relative paths (not absolute) for symlink compatibility across installation scopes
Use plain markdown syntax only—no IDE-specific syntax (no Cursor instructions, Claude directives, or Gemini-specific markup)
Behavioral files (SKILL.md body, guidelines.md, skills/.md, commands/.md, templates/, prompts/, scripts/, and _shared/**/.md) require a version bump on modification; non-behavioral files like README.md and GUIDE.md do notFor 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/SKILL.mdprd/guidelines.mdprd/GUIDE.mdprd/templates/prd.mdprd/skills/draft.mdprd/skills/clarify.mdprd/templates/section-guidance.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/SKILL.mdprd/guidelines.mdprd/GUIDE.mdprd/templates/prd.mdprd/skills/draft.mdprd/skills/clarify.mdprd/templates/section-guidance.md
**/{SKILL.md,guidelines.md,skills/*.md,commands/*.md}
📄 CodeRabbit inference engine (Custom checks)
Flag any absolute filesystem path in markdown files within workflow directories (*/SKILL.md, /skills/.md, /commands/.md, */guidelines.md). Paths like /home/, /Users/, /tmp/, /var/, /opt/ are prohibited because workflows are installed via symlink and must use relative paths only. Paths inside fenced code blocks that are clearly examples (containing "example", "e.g.", or placeholder usernames like /home/user/) are exempt.
Files:
prd/SKILL.mdprd/guidelines.mdprd/skills/draft.mdprd/skills/clarify.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:
prd/SKILL.mdprd/guidelines.md
**/SKILL.md
📄 CodeRabbit inference engine (Custom checks)
For any SKILL.md file changed in this PR, verify it is under 30 lines total (including frontmatter). SKILL.md must be thin entry points using progressive disclosure. If a SKILL.md exceeds 30 lines, flag it with the count and suggest moving content to guidelines.md or skills/ files.
Files:
prd/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:
prd/SKILL.md
**
⚙️ CodeRabbit configuration file
**: # AGENTS.mdThis file provides guidance to AI coding assistants when working with this repository.
Project Overview
This repository contains reusable AI coding workflows that can be installed globally or per-project in any environment (Cursor, Claude Code, Gemini). Each workflow is a self-contained directory with structured markdown files that AI agents can read and execute.
Current workflows:
- ai-ready — Codebase scanning and AGENTS.md generation (update)
- bugfix — Systematic bug resolution (assess, reproduce, diagnose, fix, test, review, document, pr)
- code-review — AI-driven code review with human-in-the-loop decisions (start, continue, clean)
- cve-fix — Automated CVE remediation from Jira tickets (start, scan, patch, validate, pr, backport, close)
- design — Design-and-decompose workflow (ingest, research, draft, decompose, revise, publish, respond, sync)
- docs-writer — Documentation creation workflow (gather, plan, draft, validate, apply, mr)
- e2e — Story-to-tests workflow for [QE] stories (ingest, plan, revise, code, validate, publish, respond)
- implement — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond)
- kcs — KCS Solution article workflow (gather, draft, validate, handoff)
- prd — Requirements-to-PRD workflow (ingest, clarify, draft, revise, publish, respond)
- sizing — Pre-cycle Feature sizing with T-shirt sizes and team effort breakdowns (ingest, assess, apply)
- skill-reviewer — Meta-workflow that audits AI skill directories
- triage — Bulk Jira bug triage with AI-driven categorization and HTML reports
Architecture
Workflow Structure
Every workflow follows this canonical structure:
workflow-name/ SKILL.md # Entry point with YAML frontmatter (name, version, description) guidelines.md # Behavioral rules: principles, hard limits, safety, quality README.md # Human-readable documentation (prerequ...
Files:
prd/SKILL.mdprd/guidelines.mdprd/GUIDE.mdprd/templates/prd.mdprd/skills/draft.mdprd/skills/clarify.mdprd/templates/section-guidance.md
*/guidelines.md
📄 CodeRabbit inference engine (AGENTS.md)
Every workflow must include a guidelines.md file containing behavioral rules: principles, hard limits, safety, and quality constraints
Files:
prd/guidelines.md
**/guidelines.md
⚙️ CodeRabbit configuration file
**/guidelines.md: Guidelines review (ai-workflows conventions):
- Must contain: Principles, Hard Limits, Safety, Quality, and
Escalation sections (or equivalent coverage)- Content must NOT duplicate SKILL.md or controller.md — each
file has a distinct role- Escalation criteria must be specific and actionable (not vague
"when things go wrong")- Hard limits must be concrete prohibitions, not suggestions
- All phase references should use consistent naming matching
the workflow's actual phase names
Files:
prd/guidelines.md
**/{templates,prompts}/*.md
⚙️ CodeRabbit configuration file
**/{templates,prompts}/*.md: Template/prompt review (ai-workflows conventions):
- Templates use {placeholder} syntax for caller-filled values —
verify all placeholders are documented- Prompt templates must be self-contained: the sub-agent receives
only the prompt, not the caller's context- Prompts must instruct output to .artifacts/, not inline return
- Templates must work when the workflow is installed via symlink
- No absolute paths in templates
Files:
prd/templates/prd.mdprd/templates/section-guidance.md
*/skills/*.md
📄 CodeRabbit inference engine (AGENTS.md)
*/skills/*.md: Workflows must not auto-advance phases in attended mode; they must wait for explicit user input between phases unless an unattended mode is explicitly documented
All significant workflow outputs must be persisted to .artifacts/{workflow-name}/{context}/ directory
Files:
prd/skills/draft.mdprd/skills/clarify.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:
prd/skills/draft.mdprd/skills/clarify.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/draft.mdprd/skills/clarify.md
🧠 Learnings (5)
📚 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:
prd/SKILL.md
📚 Learning: 2026-04-12T00:25:51.234Z
Learnt from: adalton
Repo: flightctl/ai-workflows PR: 20
File: design/skills/respond.md:29-31
Timestamp: 2026-04-12T00:25:51.234Z
Learning: In flightctl/ai-workflows skill markdown files, treat path references as two categories:
1) For cross-document markdown links (e.g., links to other .md files like ../skills/controller.md or ../../templates/design.md), use paths relative to the current markdown file’s location so links work under symlinks.
2) For runtime artifact paths used as prose instructions to the AI agent (e.g., .artifacts/design/{issue-number}/publish-metadata.json or .artifacts/prd/config.json), keep them repo-root-relative (start with .artifacts/). Do not convert these artifact paths to be relative to the skill file directory (e.g., don’t rewrite to ../../.artifacts/...), because the AI resolves them from the repo root.
Applied to files:
prd/skills/draft.mdprd/skills/clarify.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/draft.mdprd/skills/clarify.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/draft.mdprd/skills/clarify.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/draft.mdprd/skills/clarify.md
🔇 Additional comments (5)
prd/GUIDE.md (1)
11-12: LGTM!prd/guidelines.md (1)
20-20: LGTM!Also applies to: 36-37
prd/SKILL.md (1)
3-3: LGTM!prd/skills/draft.md (1)
8-20: LGTM!Also applies to: 75-75, 190-191
prd/templates/prd.md (1)
34-35: LGTM!Also applies to: 38-38, 42-42
amir-yogev-gh
left a comment
amir-yogev-gh
left a comment
There was a problem hiding this comment.
Review findings
Overall this is a well-structured change with consistent messaging across files. The CodeRabbit follow-up commit already addressed several edge cases (API responses in AC, "where applicable" qualifiers). Four findings survived verification:
1. prd/templates/section-guidance.md:74 — "Be concrete" NFR example is vague and unmeasurable
The new example for concrete NFRs is "Users can complete a deployment without noticeable delay" vs. the old "the system should be fast." But "without noticeable delay" is nearly as vague — it has no measurable threshold. This contradicts the file's own testability rule at line 64 ("If you can't describe how to verify it from a user's perspective, it isn't specific enough"). The first example on line 73 ("Users experience page load times under 2 seconds") is good — this second one teaches the AI that subjective phrasing is acceptable.
Failure scenario: AI drafts NFR "Users can complete a deployment without noticeable delay" following the example → QA asks "what's the target?" → no measurable acceptance threshold exists → performance regression goes undetected.
Suggestion: Use a concrete user-observable example, e.g. "Users can complete a deployment in under 30 seconds" or "Users see deployment progress update within 5 seconds."
2. prd/skills/draft.md:75 — "Elevate design details" instruction doesn't distinguish user-facing constraints from implementation choices
Step 3 says "If source material includes design details (API fields, internal architecture, code-level mechanisms), elevate them to the user-facing capability they support." User-facing constraints (validation rules, field length limits, allowed values) look like "API field design details" under this framing.
Failure scenario: Source says "name field max 64 chars, alphanumeric only" → AI elevates to "Users can name devices" → validation constraints (64-char limit, alphanumeric restriction) are dropped as "design details" even though users directly encounter them.
Suggestion: Add a carve-out: "Constraints that users directly encounter (input validation rules, length limits, allowed values, format restrictions) are user-facing requirements, not design details — preserve them."
3. prd/skills/revise.md + prd/skills/respond.md — No design-detail enforcement in revision phases
The "no design details" rule is enforced in clarify and draft, but revise.md and respond.md have no corresponding checks. A user revision or PR reviewer comment could reintroduce design details, and neither phase would flag it.
Failure scenario: PR reviewer comments "add requirement for the protocol API field" → respond phase incorporates it verbatim → published PRD contains the design detail that draft was trained to reject.
Suggestion: Add a design-detail check to the self-review or consistency steps in revise.md and respond.md, or reference the guidelines.md hard limit so it applies during those phases.
4. prd/templates/section-guidance.md:73 — NFR categories drop "scalability" and "observability"
The old list was "performance, scalability, security, compatibility, availability, observability." The new list is "responsiveness, reliability, security, accessibility, compatibility." Scalability (e.g., "support 10K concurrent users") and observability (e.g., "users can view deployment status in real time") are user-relevant qualities that don't map cleanly to the new categories.
Failure scenario: Source material includes "must handle 10,000 concurrent devices" → AI doesn't see "scalability" in the NFR category list → either omits it or awkwardly forces it under "reliability" → capacity planning constraint is lost or misframed.
Suggestion: Add "scalability" and "observability" back to the list — they are user-observable when framed correctly (capacity limits users hit, status visibility users rely on).
…s, enforce design-detail checks in revise/respond - Replace vague NFR example with measurable one - Add scalability and observability back to NFR categories - Carve out user-facing constraints (validation rules, limits) from the design-detail filter - Add design-detail enforcement to revise and respond phases Assisted-by: Claude
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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 `@prd/skills/respond.md`:
- Around line 120-124: Use a relative path for the guidelines reference in the
respond.md instructions so it resolves correctly from the file’s own location
under symlinks. Update the reference to guidelines.md in the relevant guidance
text to use ../guidelines.md, and keep this path convention consistent anywhere
the file points to other docs from prd/skills/respond.md.
In `@prd/skills/revise.md`:
- Line 59: The guidelines reference in the skills instructions uses the wrong
path; update the reference in revise.md so it points to the file relative to its
own location. Adjust the wording that mentions `guidelines.md` to use
`../guidelines.md` consistently, and keep the path rule aligned with the other
`**/skills/*.md` references in this document.
In `@prd/templates/section-guidance.md`:
- Around line 73-74: The NFR guidance in the section guidance template is too
strict about user-observable qualities and incorrectly treats API latency as out
of scope. Update the wording around the NFR examples so it keeps the
“user-observable” framing while explicitly allowing latency targets when the API
is the exposed interface, and remove or replace the `observability` example if
it cannot be user-observable. Use the existing NFR example paragraph in the
template to make this adjustment without changing the rest of the guidance.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 1e47d502-900b-458e-b306-75988cbf2618
📒 Files selected for processing (4)
prd/skills/draft.mdprd/skills/respond.mdprd/skills/revise.mdprd/templates/section-guidance.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (6)
**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
**/*.md: All file references within workflow files must use relative paths (not absolute) for symlink compatibility across installation scopes
Use plain markdown syntax only—no IDE-specific syntax (no Cursor instructions, Claude directives, or Gemini-specific markup)
Behavioral files (SKILL.md body, guidelines.md, skills/.md, commands/.md, templates/, prompts/, scripts/, and _shared/**/.md) require a version bump on modification; non-behavioral files like README.md and GUIDE.md do notFor 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/respond.mdprd/skills/revise.mdprd/templates/section-guidance.mdprd/skills/draft.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/respond.mdprd/skills/revise.mdprd/templates/section-guidance.mdprd/skills/draft.md
*/skills/*.md
📄 CodeRabbit inference engine (AGENTS.md)
*/skills/*.md: Workflows must not auto-advance phases in attended mode; they must wait for explicit user input between phases unless an unattended mode is explicitly documented
All significant workflow outputs must be persisted to .artifacts/{workflow-name}/{context}/ directory
Files:
prd/skills/respond.mdprd/skills/revise.mdprd/skills/draft.md
**/{SKILL.md,guidelines.md,skills/*.md,commands/*.md}
📄 CodeRabbit inference engine (Custom checks)
Flag any absolute filesystem path in markdown files within workflow directories (*/SKILL.md, /skills/.md, /commands/.md, */guidelines.md). Paths like /home/, /Users/, /tmp/, /var/, /opt/ are prohibited because workflows are installed via symlink and must use relative paths only. Paths inside fenced code blocks that are clearly examples (containing "example", "e.g.", or placeholder usernames like /home/user/) are exempt.
Files:
prd/skills/respond.mdprd/skills/revise.mdprd/skills/draft.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:
prd/skills/respond.mdprd/skills/revise.mdprd/skills/draft.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/respond.mdprd/skills/revise.mdprd/skills/draft.md
**
⚙️ CodeRabbit configuration file
**: # AGENTS.mdThis file provides guidance to AI coding assistants when working with this repository.
Project Overview
This repository contains reusable AI coding workflows that can be installed globally or per-project in any environment (Cursor, Claude Code, Gemini). Each workflow is a self-contained directory with structured markdown files that AI agents can read and execute.
Current workflows:
- ai-ready — Codebase scanning and AGENTS.md generation (update)
- bugfix — Systematic bug resolution (assess, reproduce, diagnose, fix, test, review, document, pr)
- code-review — AI-driven code review with human-in-the-loop decisions (start, continue, clean)
- cve-fix — Automated CVE remediation from Jira tickets (start, scan, patch, validate, pr, backport, close)
- design — Design-and-decompose workflow (ingest, research, draft, decompose, revise, publish, respond, sync)
- docs-writer — Documentation creation workflow (gather, plan, draft, validate, apply, mr)
- e2e — Story-to-tests workflow for [QE] stories (ingest, plan, revise, code, validate, publish, respond)
- implement — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond)
- kcs — KCS Solution article workflow (gather, draft, validate, handoff)
- prd — Requirements-to-PRD workflow (ingest, clarify, draft, revise, publish, respond)
- sizing — Pre-cycle Feature sizing with T-shirt sizes and team effort breakdowns (ingest, assess, apply)
- skill-reviewer — Meta-workflow that audits AI skill directories
- triage — Bulk Jira bug triage with AI-driven categorization and HTML reports
Architecture
Workflow Structure
Every workflow follows this canonical structure:
workflow-name/ SKILL.md # Entry point with YAML frontmatter (name, version, description) guidelines.md # Behavioral rules: principles, hard limits, safety, quality README.md # Human-readable documentation (prerequ...
Files:
prd/skills/respond.mdprd/skills/revise.mdprd/templates/section-guidance.mdprd/skills/draft.md
**/{templates,prompts}/*.md
⚙️ CodeRabbit configuration file
**/{templates,prompts}/*.md: Template/prompt review (ai-workflows conventions):
- Templates use {placeholder} syntax for caller-filled values —
verify all placeholders are documented- Prompt templates must be self-contained: the sub-agent receives
only the prompt, not the caller's context- Prompts must instruct output to .artifacts/, not inline return
- Templates must work when the workflow is installed via symlink
- No absolute paths in templates
Files:
prd/templates/section-guidance.md
🧠 Learnings (4)
📚 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/respond.mdprd/skills/revise.mdprd/skills/draft.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/respond.mdprd/skills/revise.mdprd/skills/draft.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/respond.mdprd/skills/revise.mdprd/skills/draft.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/respond.mdprd/skills/revise.mdprd/skills/draft.md
🔇 Additional comments (1)
prd/skills/draft.md (1)
75-75: LGTM!Also applies to: 190-191
|
Thanks for the thorough review — all four findings addressed in b5f3f1e:
|
- Use ../guidelines.md in revise.md and respond.md (symlink-safe) - Clarify that API-level targets are valid NFRs when the API is the user's interface Assisted-by: Claude
There was a problem hiding this comment.
♻️ Duplicate comments (1)
prd/templates/section-guidance.md (1)
73-73: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDrop
observabilityfrom the user-observable examples.
observabilitystill reads like an implementation concern, which undercuts the rule’s user-facing framing.♻️ Proposed fix
- - Frame NFRs as **user-observable qualities**: responsiveness, reliability, scalability, security, accessibility, compatibility, observability. For example, "Users experience page load times under 2 seconds" not "the system should be fast." When the API is the user's interface, API-level targets like "Users receive API responses within 200ms at p95" are valid user-observable NFRs. + - Frame NFRs as **user-observable qualities**: responsiveness, reliability, scalability, security, accessibility, and compatibility. For example, "Users experience page load times under 2 seconds" not "the system should be fast." When the API is the user's interface, API-level targets like "Users receive API responses within 200ms at p95" are valid user-observable NFRs.🤖 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/templates/section-guidance.md` at line 73, Update the NFR guidance in the section-guidance template to remove observability from the user-observable examples list. Keep the wording focused on user-facing qualities in the same sentence that mentions responsiveness, reliability, scalability, security, accessibility, and compatibility, and ensure the example text still uses user-observable phrasing.
🤖 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.
Duplicate comments:
In `@prd/templates/section-guidance.md`:
- Line 73: Update the NFR guidance in the section-guidance template to remove
observability from the user-observable examples list. Keep the wording focused
on user-facing qualities in the same sentence that mentions responsiveness,
reliability, scalability, security, accessibility, and compatibility, and ensure
the example text still uses user-observable phrasing.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 88ede07d-0033-4958-9427-ba384f087091
📒 Files selected for processing (3)
prd/skills/respond.mdprd/skills/revise.mdprd/templates/section-guidance.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (6)
**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
**/*.md: All file references within workflow files must use relative paths (not absolute) for symlink compatibility across installation scopes
Use plain markdown syntax only—no IDE-specific syntax (no Cursor instructions, Claude directives, or Gemini-specific markup)
Behavioral files (SKILL.md body, guidelines.md, skills/.md, commands/.md, templates/, prompts/, scripts/, and _shared/**/.md) require a version bump on modification; non-behavioral files like README.md and GUIDE.md do notFor 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/respond.mdprd/skills/revise.mdprd/templates/section-guidance.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/respond.mdprd/skills/revise.mdprd/templates/section-guidance.md
*/skills/*.md
📄 CodeRabbit inference engine (AGENTS.md)
*/skills/*.md: Workflows must not auto-advance phases in attended mode; they must wait for explicit user input between phases unless an unattended mode is explicitly documented
All significant workflow outputs must be persisted to .artifacts/{workflow-name}/{context}/ directory
Files:
prd/skills/respond.mdprd/skills/revise.md
**/{SKILL.md,guidelines.md,skills/*.md,commands/*.md}
📄 CodeRabbit inference engine (Custom checks)
Flag any absolute filesystem path in markdown files within workflow directories (*/SKILL.md, /skills/.md, /commands/.md, */guidelines.md). Paths like /home/, /Users/, /tmp/, /var/, /opt/ are prohibited because workflows are installed via symlink and must use relative paths only. Paths inside fenced code blocks that are clearly examples (containing "example", "e.g.", or placeholder usernames like /home/user/) are exempt.
Files:
prd/skills/respond.mdprd/skills/revise.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:
prd/skills/respond.mdprd/skills/revise.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/respond.mdprd/skills/revise.md
**
⚙️ CodeRabbit configuration file
**: # AGENTS.mdThis file provides guidance to AI coding assistants when working with this repository.
Project Overview
This repository contains reusable AI coding workflows that can be installed globally or per-project in any environment (Cursor, Claude Code, Gemini). Each workflow is a self-contained directory with structured markdown files that AI agents can read and execute.
Current workflows:
- ai-ready — Codebase scanning and AGENTS.md generation (update)
- bugfix — Systematic bug resolution (assess, reproduce, diagnose, fix, test, review, document, pr)
- code-review — AI-driven code review with human-in-the-loop decisions (start, continue, clean)
- cve-fix — Automated CVE remediation from Jira tickets (start, scan, patch, validate, pr, backport, close)
- design — Design-and-decompose workflow (ingest, research, draft, decompose, revise, publish, respond, sync)
- docs-writer — Documentation creation workflow (gather, plan, draft, validate, apply, mr)
- e2e — Story-to-tests workflow for [QE] stories (ingest, plan, revise, code, validate, publish, respond)
- implement — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond)
- kcs — KCS Solution article workflow (gather, draft, validate, handoff)
- prd — Requirements-to-PRD workflow (ingest, clarify, draft, revise, publish, respond)
- sizing — Pre-cycle Feature sizing with T-shirt sizes and team effort breakdowns (ingest, assess, apply)
- skill-reviewer — Meta-workflow that audits AI skill directories
- triage — Bulk Jira bug triage with AI-driven categorization and HTML reports
Architecture
Workflow Structure
Every workflow follows this canonical structure:
workflow-name/ SKILL.md # Entry point with YAML frontmatter (name, version, description) guidelines.md # Behavioral rules: principles, hard limits, safety, quality README.md # Human-readable documentation (prerequ...
Files:
prd/skills/respond.mdprd/skills/revise.mdprd/templates/section-guidance.md
**/{templates,prompts}/*.md
⚙️ CodeRabbit configuration file
**/{templates,prompts}/*.md: Template/prompt review (ai-workflows conventions):
- Templates use {placeholder} syntax for caller-filled values —
verify all placeholders are documented- Prompt templates must be self-contained: the sub-agent receives
only the prompt, not the caller's context- Prompts must instruct output to .artifacts/, not inline return
- Templates must work when the workflow is installed via symlink
- No absolute paths in templates
Files:
prd/templates/section-guidance.md
🧠 Learnings (4)
📚 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/respond.mdprd/skills/revise.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/respond.mdprd/skills/revise.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/respond.mdprd/skills/revise.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/respond.mdprd/skills/revise.md
🪛 LanguageTool
prd/templates/section-guidance.md
[grammar] ~73-~73: Ensure spelling is correct
Context: ...ike "Users receive API responses within 200ms at p95" are valid user-observable NFRs....
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (2)
prd/skills/respond.md (1)
120-125: LGTM!prd/skills/revise.md (1)
59-59: LGTM!
adalton
left a comment
adalton
left a comment
There was a problem hiding this comment.
Solid PR. The intent — keeping PRDs focused on user capabilities rather than drifting into design territory — is clearly motivated, and the execution covers every phase end-to-end so design details can't re-enter through feedback loops.
The elevation pattern in draft.md step 3 is the key insight: don't just reject design details, translate them back to the user capability they support. The carve-out for user-facing constraints (validation rules, length limits) prevents overcorrection. The nuance around API-as-interface is well handled after the fixup commits.
One minor suggestion inline about splitting a dense instruction step. Version bump to 0.3.0 is correct per the versioning rules.
| 1. Read the section guidance for that section | ||
| 2. Draw content from the source material | ||
| 3. Apply the quality standards (measurable goals, testable requirements, verifiable acceptance criteria) | ||
| 3. Apply the quality standards (measurable goals, testable requirements, user-verifiable acceptance criteria). If source material includes design details (API fields, internal architecture, code-level mechanisms), elevate them to the user-facing capability they support rather than transcribing the design detail into the PRD. Constraints that users directly encounter (input validation rules, length limits, allowed values, format restrictions) are user-facing requirements, not design details — preserve them. |
There was a problem hiding this comment.
Nit: Step 3 now carries three distinct instructions — quality standards, design-detail elevation, and the constraint carve-out — in a single sentence. The other steps are crisp one-liners. When multiple instructions are packed into one step, the AI is more likely to weight them equally or drop the subtler one (the constraint carve-out) under pressure.
Consider splitting the elevation logic into its own step, e.g.:
3. Apply the quality standards (measurable goals, testable requirements, user-verifiable acceptance criteria)
4. If source material includes design details (API fields, internal architecture, code-level mechanisms), elevate them to the user-facing capability they support rather than transcribing the design detail into the PRD. Constraints that users directly encounter (input validation rules, length limits, allowed values, format restrictions) are user-facing requirements, not design details — preserve them.
(renumbering subsequent steps accordingly)
There was a problem hiding this comment.
Good catch — split into its own step in 939cc3b. Quality standards, design elevation, and constraint carve-out are now three distinct instructions the AI processes separately.
Per review feedback, the design-detail elevation and constraint carve-out were packed into the same step as quality standards. Split into its own step so the AI treats each instruction distinctly. Assisted-by: Claude
|
@amir-yogev-gh @adalton Please review again |
3 participants
Summary
guidelines.md— PRDs must not include API fields, internal architecture, code locations, or non-user-observable behaviorFiles changed
prd/guidelines.mdprd/templates/section-guidance.mdprd/templates/prd.mdprd/skills/draft.mdprd/skills/clarify.mdprd/GUIDE.mdprd/SKILL.mdTest plan
/prd:drafton a Jira issue that describes capabilities in API terms — verify the output describes UI/CLI/API, not API-only/prd:clarifyon source material with API-only language — verify it asks about UI/CLI interfaces🤖 Generated with Claude Code
Affected workflows: PRD guidance and workflow docs—specifically the PRD workflow’s skills/phases (clarify, draft, revise, respond), the PRD template generation content (PRD template + section guidance), and shared conventions within the PRD workflow documentation (e.g., how to describe requirements and handle UI/CLI/API).
Structural/behavioral changes:
0.2.0to0.3.0(prd/SKILL.md).prd/guidelines.md, requiring PRDs to describe only user-observable behavior/outcomes and explicitly forbidding design/implementation details (e.g., specific API fields, internal architecture, code locations, and other non-user-observable behavior).prd/skills/revise.md: added a consistency-check bullet to flag any revisions introducing design details and elevate them back to user-facing capabilities per the “No design details” limit.prd/skills/respond.md: added a “Check for design details” gate before applying edits/resolutions, requiring elevation/translation of any design-detail content into user-facing capabilities.prd/GUIDE.md: introduced/expanded the “User-facing focus” principle (capabilities + observable outcomes; no implementation/design details).prd/templates/prd.md: updated FR/NFR placeholder wording and acceptance-criteria checkbox text to be explicitly user-perspective and user-verifiable.prd/templates/section-guidance.md:prd/skills/clarify.md: replaced gap-analysis categories with a user-centered set (users/personas, user capabilities, user-observable qualities) and added process rules to keep clarification questions focused on user needs/capabilities. Also added guidance to determine whether a capability is exposed via UI/CLI before treating the API as optional.prd/skills/draft.md:Shared resources / cross-workflow conventions:
_shared/resources were indicated.