[NE-2195] Add initial add-enhancement command #1870

rikatz · 2025-10-21T18:11:47Z

This change adds an intiial "add-enhancement" to be used by Claude. The idea is to reduce the time of bootstrapping a new enhancement proposal, by using the current template and some well known questions and fill as much as possible the EP template for the caller.

Example of a generated proposal: #1871

rikatz · 2025-10-22T17:12:26Z

Add a requirement of adding proper line breaks on column 80 to make readability of reviewers better
Add requirement for a Jira ticket (if the ticket is public Claude can also read from it)
Should the user stories be scoped to a set of personas?
Improve API extension field to just add something if an API/Webhook/CRD is really created/modified
Enforce: While it is useful to go into the details of the code changes required, it is not necessary to show how the code will be rewritten in the enhancement.

.claude/commands/add-enhancement.md

bentito · 2025-10-28T14:35:48Z

.claude/commands/add-enhancement.md

+   - Ensure the area directory exists under `enhancements/`
+   - Create a valid filename from the name (lowercase, replace spaces with dashes)
+   - Verify all required YAML metadata is present
+   - Verify the JIRA ticket URL is included in the tracking-link metadata field


Perhaps add Run make verify to satisfy lint checks? -- I think it has an environment to handle this, right?

huum, good call. I was going to do it, but sadly the make lint was created for podman only, and I didn't wanted to change/fix on this PR (to not mix things).

Maybe should be done as a followup:

Fix makefile/make it more generic

Add to the command to run a make lint

wdyt?

For sure, maybe add an issue for the follow-up and link here?

bentito

Just a bunch of nits, let me know what you think or make changes as you feel needed, and I'll smash the approve button.

rikatz · 2025-10-28T16:30:39Z

added some fixes, commented on other review suggestions

.claude/commands/add-enhancement.md

bentito · 2025-11-03T16:49:35Z

/lgtm

Miciah

/approve
/hold
in case you want to address any of my comments first. Feel free to /hold cancel.

Miciah · 2025-11-03T19:53:27Z

.claude/commands/add-enhancement.md

+
+## Instructions
+
+Act as an experienced software architect to create a comprehensive enhancement proposal. Follow these steps:


Hm, I wonder whether this "Act as an experienced software architect" phrase contributes to the confidently wrong nature of the output. Maybe, "Act as a competent, experienced software architect with impostor syndrome"? (Ha ha, only serious.)

so, my worry here is that whatever we add as a context will be the used context, so adding something like impostor syndrome will just add wrong things as a question instead of as a conclusion :D and I know exactly how it is!

Fair enough. It wasn't an entirely serious suggestion, coaxing an LLM not to be overconfidently wrong is probably requires more finesse than that, and it makes sense to prioritize addressing the problem from the other side (that is, cultivating a healthy skepticism of LLM output).

Miciah · 2025-11-03T19:53:28Z

.claude/commands/add-enhancement.md

+   - Specific user stories or motivations if not clear from the description
+   - Explicit Goals or Non-Goals the user wants included
+   - Any specific technical constraints or requirements
+   - Topology considerations (Hypershift, SNO, MicroShift relevance)


If #1883 gets approved, you can add "OKE" to this list (or I can update #1883 to add "OKE" to this list).

I can wait for yours to be merged first, so this gives more context to claude on what is OKE

I have requested some OKE consideration as well (look at my last commit)

Miciah · 2025-11-03T19:56:36Z

.claude/commands/add-enhancement.md

     - **Workflow Description**: Detailed workflow with actors and steps
     - **Mermaid Diagram**: Add a sequence diagram when applicable to visualize the workflow
-     - **Metadata**: Fill in creation-date with today's date (2025-10-21), set other fields to TBD
+     - **API Extensions**: Only fill this section if the user confirms the proposal adds/changes CRDs, admission and conversion webhooks, aggregated API servers, or finalizers. Otherwise, add a TODO comment asking the user to complete this section if applicable.


Now we also have ValidatingAdmissionPlugin and MutatingAdmissionPlugin as well!

added as part of my last commit

Miciah · 2025-11-03T19:57:44Z

.claude/commands/add-enhancement.md

   - Focus on the essential information
   - Use bullet points and structured formatting
   - Avoid unnecessary verbosity
+   - **Line Length**: Keep lines in the generated enhancement at a maximum of 80 characters. It is acceptable to exceed by 10-15 characters when necessary (e.g., for URLs or code examples), but not more than that.


What happens with a URL that exceeds 95 characters?

let me test here :)

enforced the requirement on my last commit

openshift-ci · 2025-11-03T19:59:37Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: Miciah

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [Miciah]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

Add refinement to stop breaking lines if it turns them invalid (URL, code), to support OKE, and some other refinements on how the enhancement should be generated

openshift-ci · 2025-11-04T16:07:46Z

@rikatz: all tests passed!

Full PR test history. Your PR dashboard.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

Miciah · 2025-11-04T16:46:45Z

.claude/commands/add-enhancement.md

-     - **API Extensions**: Only fill this section if the user confirms the proposal adds/changes CRDs, admission and conversion webhooks, aggregated API servers, or finalizers. Otherwise, add a TODO comment asking the user to complete this section if applicable.
-     - **Implementation Details/Notes/Constraints**: Provide a high-level overview of the code changes required. Follow the guidance from the template: "While it is useful to go into the details of the code changes required, it is not necessary to show how the code will be rewritten in the enhancement." Keep it as an overview; the developer should fill in the specific implementation details.
-     - **Metadata**: Fill in creation-date with today's date, tracking-link with the provided JIRA ticket URL, set other fields to TBD
+     - **Mermaid Diagram**: Add a sequence diagram when the workflow involves multiple actors or complex interactions between components (e.g., user -> API server -> controller -> operator). Simple single-actor workflows may not need a diagram.


Is the model going to interpret that example as you expect it to? I'm curious because the example represents multiple actors but not complex interactions, and it is ambiguous whether it is an example of "multiple actors or complex interactions between components" or an example of "a sequence diagram". I'm also curious how the model acts on instructions such as "may not need".

I think it is mostly like "if it decides that are multiple components", but IMO we can always just ask the model later "btw, generate a mermaid diagram for me" and it does a really decent job :)

Miciah · 2025-11-04T16:47:09Z

/lgtm

rikatz · 2025-11-04T16:56:55Z

/hold cancel
Merging this, thanks all for all the reviews!
I think we can iterate over this command later if we find some improvements that are required!

openshift-ci bot requested review from derekwaynecarr and dustymabe October 21, 2025 18:12

bentito reviewed Oct 28, 2025

View reviewed changes

.claude/commands/add-enhancement.md Show resolved Hide resolved

bentito reviewed Oct 28, 2025

View reviewed changes

.claude/commands/add-enhancement.md Outdated Show resolved Hide resolved

bentito reviewed Oct 28, 2025

View reviewed changes

.claude/commands/add-enhancement.md Outdated Show resolved Hide resolved

bentito reviewed Oct 28, 2025

View reviewed changes

.claude/commands/add-enhancement.md Show resolved Hide resolved

bentito reviewed Oct 28, 2025

View reviewed changes

bentito reviewed Nov 3, 2025

View reviewed changes

.claude/commands/add-enhancement.md Show resolved Hide resolved

openshift-ci bot assigned bentito Nov 3, 2025

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Nov 3, 2025

Miciah reviewed Nov 3, 2025

View reviewed changes

openshift-ci bot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Nov 3, 2025

openshift-ci bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Nov 3, 2025

rikatz changed the title ~~Add initial add-enhancement command~~ [NE-2195] Add initial add-enhancement command Nov 4, 2025

rikatz added 4 commits November 4, 2025 11:51

Add initial add-enhancement command

3670aa0

Refine enhancement command requirements

e005ec2

Fix the add-enhancement based on review

69ca07c

Refine add-enhancement command

cda54c9

Add refinement to stop breaking lines if it turns them invalid (URL, code), to support OKE, and some other refinements on how the enhancement should be generated

rikatz force-pushed the add-enhancement-command branch from 269b20e to cda54c9 Compare November 4, 2025 15:39

openshift-ci bot removed the lgtm Indicates that a PR is ready to be merged. label Nov 4, 2025

Miciah reviewed Nov 4, 2025

View reviewed changes

openshift-ci bot assigned Miciah Nov 4, 2025

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Nov 4, 2025

openshift-ci bot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Nov 4, 2025

openshift-merge-bot bot merged commit 10e8fd8 into openshift:master Nov 4, 2025
2 checks passed


		## Instructions

		Act as an experienced software architect to create a comprehensive enhancement proposal. Follow these steps:

[NE-2195] Add initial add-enhancement command #1870

[NE-2195] Add initial add-enhancement command #1870

Uh oh!

Conversation

rikatz commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rikatz commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bentito left a comment

Choose a reason for hiding this comment

Uh oh!

rikatz commented Oct 28, 2025

Uh oh!

Uh oh!

bentito commented Nov 3, 2025

Uh oh!

Miciah left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

openshift-ci bot commented Nov 3, 2025

Uh oh!

openshift-ci bot commented Nov 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Miciah commented Nov 4, 2025

Uh oh!

rikatz commented Nov 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rikatz commented Oct 21, 2025 •

edited

Loading

rikatz commented Oct 22, 2025 •

edited

Loading