Guided authoring of Helm Improvement Proposals (HIPs). Use this skill when the user wants to write a HIP, create a proposal, draft a HIP, start a new HIP, or mentions writing a Helm Improvement Proposal. Also trigger when the user says things like 'I have an idea for Helm' or 'I want to propose a change to Helm' or 'new proposal' in the context of this repository.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Guided authoring of Helm Improvement Proposals (HIPs). Use this skill when the user wants to write a HIP, create a proposal, draft a HIP, start a new HIP, or mentions writing a Helm Improvement Proposal. Also trigger when the user says things like 'I have an idea for Helm' or 'I want to propose a change to Helm' or 'new proposal' in the context of this repository.
HIP Authoring Guide
This skill walks users through creating a Helm Improvement Proposal from an initial idea to a complete, submission-ready document.
The process has two phases: idea refinement (getting the concept sharp before writing) and section-by-section drafting (producing each section, pausing for the user to edit, then asking clarifying questions before moving on).
Read references/hip-template.md for the canonical template, preamble format, required sections, length recommendations, and approval requirements. Use it as the structural backbone for every HIP you help draft.
Phase 1: Idea Refinement
Before writing anything, help the user sharpen their idea. A focused proposal is far more likely to succeed — the Helm maintainers will reject proposals that are too broad or unfocused.
Step 1: Understand the idea
Ask the user to describe their idea in plain language. Listen for:
What problem does this solve?
Who experiences this problem? (chart authors, cluster operators, end users, maintainers)
Is this a change to Helm's code (feature), a process/governance change (process), or documentation/guidance (informational)?
Has this been discussed in #helm-dev on Kubernetes Slack or at the weekly developer call (Thursdays 9:30am US Pacific)? If not, strongly recommend they vet the idea there first. The #helm-dev channel is where active development discussion happens and is the fastest way to get initial feedback on whether an idea is worth writing up as a HIP. Ideas that have been previously rejected or are out of scope for the project will be caught early, saving significant effort.
Step 2: Scope gate
This step is critical. The single most common reason HIPs get rejected or stall is being too broad. Apply these tests:
Single-concept test: Can you explain the core of this proposal in one sentence without using "and" to join independent ideas? If not, it needs splitting.
Independence test: Does the proposal contain sub-features that could ship independently? If removing part of the proposal still leaves something valuable, the removed part should be its own HIP.
MVP test: What is the absolute simplest version of this that delivers value? Start there. Enhancements can be follow-up HIPs.
If the idea fails these tests, do NOT proceed. Instead:
Name the independent pieces explicitly
Help the user pick which single piece to write up first
Explain that focused HIPs move faster through review and are more likely to be accepted
Only proceed when the user has committed to a single, focused proposal.
Step 3: Feasibility check
Ask targeted questions about impact:
Are there backwards compatibility concerns? If this changes existing behavior, the bar is significantly higher.
Does this require changes across multiple Helm projects (helm, helm-www, chartmuseum, etc.), or is it scoped to one?
Is there prior art in other package managers or CNCF projects?
What's the rough implementation complexity? (This informs how much detail the Specification needs.)
Step 4: Identify the type
Based on the discussion, confirm the HIP type:
feature — most common; proposes a new capability or interoperability standard
process — changes to how the project operates (governance, release process, tooling). Requires org maintainer approval rather than project maintainer approval.
informational — guidance or conventions; non-binding
Step 5: Summarize and confirm
Present a crisp 2-3 sentence summary of the proposal back to the user. This summary will become the seed for the Abstract. Ask: "Does this capture your idea? What would you change?"
Do not proceed to Phase 2 until the user explicitly confirms the idea is well-scoped and accurately summarized.
Phase 2: Section-by-Section Drafting
Work through each section one at a time. For every section:
Draft the section content based on everything discussed so far.
Present the draft to the user with the section header, and ask them to edit directly or suggest changes.
Wait for the user to confirm or revise. If they revise, incorporate their changes.
Clarify — before moving to the next section, ask 1-2 targeted questions that will inform the upcoming sections. These questions should arise naturally from what was just written.
Drafting principle: write each section as simply as possible while fully serving its purpose. Each section below states what it must accomplish and gives a target (what is usually enough) and a ceiling (both drawn from real HIPs; see references/hip-template.md for full ranges). Aim for the target and treat the ceiling as a limit to stay under — not a quota to fill. If a section's purpose is met in fewer words, leave it shorter; reviewers reward focus, and padding buries the substance. Exceed the ceiling only when the section genuinely needs it (a detailed Specification, a breaking-change migration).
Section order
1. Preamble
Generate the YAML frontmatter. Use hip: 9999 as the placeholder number, today's date for created, status: "draft", and the type determined in Phase 1. Ask the user for their preferred author format (with or without email).
2. Abstract
Target ~50 words (ceiling ~100). Draw from the summary confirmed in Phase 1. The abstract must be self-contained — a reader should understand what the proposal does without reading further. Avoid implementation details.
Before moving on, ask: "What existing workarounds do people use today? Understanding the current pain points will strengthen the Motivation section."
3. Motivation
Target ~150 words (ceiling ~200). This section is critical — proposals without sufficient motivation get rejected outright. Use subheadings to organize, including only those that carry weight for this proposal:
Current Limitations — what can't users do today?
Real-World Impact — concrete examples, not hypotheticals
Who Is Affected — name specific roles
Existing Workarounds (optional) — what do people do today, and why is it inadequate?
Before moving on, ask: "What alternative approaches did you consider? Why did you land on this design rather than those alternatives?"
4. Rationale
Target ~100 words (ceiling ~150). Explain the "why" behind key design decisions. Use subheadings for distinct decisions (e.g., "### Why X over Y"). Cover:
Why this approach over the alternatives discussed
How similar problems are handled in other projects if relevant
Key tradeoffs made and why they're acceptable
Before moving on, ask: "Can you describe the technical details? What would the API, CLI interface, data structures, or behavior look like?"
5. Specification
Target ~350 words (ceiling ~680 for complex features). Usually the most detailed section. For feature HIPs, it must be detailed enough for someone else to implement — but only as detailed as that requires. Include:
Data structures, CLI flags, API shapes as appropriate
Behavior matrix if there are multiple modes or contexts
Edge cases and how they're handled
For process HIPs, define concrete steps, timelines, roles, and decision criteria rather than code.
Before moving on, ask: "Does this change break anything for existing users? Could someone on an older version of Helm be affected?"
6. Backwards Compatibility
Target ~30 words (ceiling ~90). Often a single sentence — for purely additive changes, confirming no breakage is enough. For breaking changes, be explicit about severity, migration path, and whether a major version is required.
Before moving on, ask: "Could someone misuse this feature? What's the worst case from a security perspective?"
7. Security Implications
Target ~20 words (ceiling ~40). Often one line ("No security implications") for benign features. For features touching data exposure or trust boundaries, cover attack surface, risks, and mitigations.
Before moving on, ask: "If you were writing docs for this, what's the one example you'd lead with? How would you explain this to a new Helm user?"
8. How to Teach This
Target ~50 words (ceiling ~70). Cover the documentation impact and nothing more:
Documentation additions or changes needed
The key example pattern users should follow
How this fits into concepts users already know
9. Reference Implementation
Target ~15 words (ceiling ~20). Usually one line: link to a PR, or briefly describe what the implementation will involve. If nothing exists yet, a short description is fine.
10. Rejected Ideas
Target ~50 words (ceiling ~100). Capture alternatives discussed (in Phase 1 and during drafting) with brief explanations of why they were rejected. Use a bulleted list — each entry 1-2 sentences.
11. Open Issues
Target ~15 words (ceiling ~50). Any unresolved questions, kept brief. Fine to submit a draft HIP with open issues — they're resolved during review.
12. References
Target ~20 words (ceiling ~40). Collect all URLs, specs, and materials referenced throughout the HIP.
Optional sections
Offer these when appropriate:
Scope — when the proposal is large, explicitly stating what is NOT in scope helps focus review. Offer this after Phase 1 if the user's idea required significant narrowing.
Implementation Plan — for complex multi-phase features, a phased delivery plan with milestones. Offer this if the Specification describes something that would naturally ship incrementally.
Phase 3: Assembly and Review
After all sections are drafted and the user has reviewed each one:
Assemble the complete HIP document in the correct order
Write it to hips/hip-9999.md (placeholder number)
Remind the user to:
Add the HIP to the listing in hips/README.md once a real number is assigned
Submit as a PR to helm/community
Each commit must be signed off (DCO requirement)
The HIP needs at least 2 approvals (from project maintainers for feature/informational, from org maintainers for process)
Strongly recommend: if the user hasn't already vetted this idea in #helm-dev on Kubernetes Slack or at the weekly Thursday developer call, suggest they do so before or alongside submitting the PR. Getting early maintainer feedback prevents lengthy review cycles and reduces the chance of outright rejection.
