Fix PRD section numbering gaps when optional sections are omitted

[avishayt]

Summary

• Added "Keep numbering sequential" rule to prd/skills/draft.md so the AI renumbers remaining sections when optional ones (e.g., 2.2 Success Metrics, section 5 Assumptions) are omitted
• Added matching renumber-on-delete instructions to prd/skills/revise.md and prd/skills/respond.md
• Fixed prd/README.md which listed only 7 template sections instead of 8 (missing Assumptions, with wrong numbers for Dependencies/Risks/Open Questions)

Test plan

• Run /draft on a Jira issue that has no quantifiable success metrics — verify section 2 goes 2.1 Goals, 2.2 Non-Goals (no gap)
• Run /draft on a Jira issue with no assumptions or dependencies — verify remaining sections are numbered sequentially
• Run /revise to delete a section — verify remaining sections are renumbered
• Verify README section list matches the actual template

🤖 Generated with Claude Code

Affected workflows: PRD drafting (/draft), PRD revising (/revise), and PRD responding (/respond).

Behavioral changes:

• prd/skills/draft.md: adds a “Keep numbering sequential” critical rule so if optional PRD sections/subsections are omitted, subsequent headings are renumbered to eliminate numbering gaps.
• prd/skills/revise.md: strengthens deletion guidance to remove content while checking for orphaned references; if an entire section/subsection is deleted, remaining sections are renumbered to close numbering gaps.
• prd/skills/respond.md: when resolving reviewer feedback causes the “Open Questions” section to become empty, the skill instructs removing that section and renumbering subsequent PRD sections to close the gap.

Structural changes:

• prd/README.md: updates the “PRD Template” outline to include “4. Acceptance Criteria” and corrects numbering/order for “5. Assumptions”, “6. Dependencies”, “7. Risks”, and “8. Open Questions”, ensuring all 8 template sections are listed.

Shared resources / cross-workflow conventions:

• No changes to _shared/.
• Cross-workflow convention updated: sequential section numbering is consistently enforced across draft/revise/respond when optional or deleted sections would otherwise create gaps.

Also:

• prd/SKILL.md increments the documented workflow version from 0.3.0 to 0.4.0.

[coderabbitai]

Walkthrough

Documentation and skill instructions were updated to include a missing PRD template section and to require renumbering when optional or removed sections leave gaps.

Changes

PRD Numbering Documentation

Layer / File(s)	Summary
PRD template correction prd/README.md	Adds a “4. Acceptance Criteria” template entry and renumbers the following PRD sections.
Sequential renumbering rules prd/skills/draft.md, prd/skills/respond.md, prd/skills/revise.md, prd/SKILL.md	Adds explicit sequential-renumbering instructions for omitted or removed sections and updates the skill version front-matter.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• flightctl/ai-workflows#40: Also changes PRD respond/open-question handling and downstream section renumbering behavior.

Suggested labels: workflow-structure, documentation

Suggested reviewers: amir-yogev-gh, eranco74

🚥 Pre-merge checks | ✅ 12

✅ Passed checks (12 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Ai-Attribution	✅ Passed	AI use is disclosed and the HEAD commit includes an acceptable Assisted-by trailer; no Co-Authored-By AI trailer found.
No-Absolute-Paths-In-Skills	✅ Passed	Only absolute paths found were /home/user examples inside fenced JSON blocks, which are explicitly exempt; no prohibited paths in the PR files.
Skill-Md-Under-30-Lines	✅ Passed	prd/SKILL.md is the only changed SKILL.md and it totals 26 lines including frontmatter, under the 30-line limit.
Command-Colon-Notation	✅ Passed	PR only changes prd README/skills files; no commands/ files are in the diff, so the colon-notation rule is not applicable.
No-Orphaned-References	✅ Passed	All backtick path refs in changed PRD docs resolve to existing files, and every PRD skill/command file is referenced from SKILL.md/controller.md/commands; no orphans.
No-Content-Duplication	✅ Passed	prd/SKILL.md only has brief cross-references; no substantial verbatim multi-line duplication with prd/guidelines.md or prd/skills/controller.md.
Step-Sequencing	✅ Passed	PASS: draft/respond/revise each have sequential main steps (9/6/6), with no gaps or duplicates and none over 10 steps.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: fixing PRD section numbering gaps when optional sections are omitted.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-prd-section-numbering

---

_{Comment @coderabbitai help to get the list of available commands.}