HIP author skill

.agents/skills/hip-author/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: hip-author
+description: "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](https://kubernetes.slack.com/messages/C51E88VDG) on Kubernetes Slack or at the [weekly developer call](https://calendar.google.com/calendar/embed?src=s5anaqbm9kda435dnh5r8lj1l8%40group.calendar.google.com&ctz=America%2FLos_Angeles) (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:
+
+1. **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.
+2. **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.
+3. **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:
+
+1. **Draft** the section content based on everything discussed so far. Use the length guidance from `references/hip-template.md` — aim for the "typical" range, not the maximum.
+2. **Present** the draft to the user with the section header, and ask them to edit directly or suggest changes.
+3. **Wait** for the user to confirm or revise. If they revise, incorporate their changes.
+4. **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.
+
+### 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 (existing HIPs average 67, median 46). Draw from the summary confirmed in Phase 1. The abstract should 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. This section is critical — proposals without sufficient motivation get rejected outright. Use subheadings to organize:
+
+- **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. 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 (the largest section). For feature HIPs, this needs to be detailed enough for someone else to implement. Include:
+
+- Data structures, CLI flags, API shapes as appropriate
+- Usage examples showing realistic scenarios (use code blocks)
+- 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. Often short — for purely additive changes, a sentence confirming no breakage is sufficient. 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. Can be very brief ("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. Document:
+
+- 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. Link to a PR or describe what the implementation will involve. If nothing exists yet, a brief description of what the implementation entails is fine.
+
+#### 10. Rejected Ideas
+
+Target ~50 words. Capture alternatives discussed (in Phase 1 and during drafting) with brief explanations of why they were rejected. Use a bulleted list — each entry should be 1-2 sentences.
+
+#### 11. Open Issues
+
+Target ~15 words. Any unresolved questions. Fine to submit a draft HIP with open issues — they're resolved during review.
+
+#### 12. References
+
+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:
+
+1. Assemble the complete HIP document in the correct order
+2. Write it to `hips/hip-9999.md` (placeholder number)
+3. 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)
+4. 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.

.agents/skills/hip-author/references/hip-template.md

@@ -0,0 +1,156 @@
+# HIP Template and Reference
+
+This file contains the canonical HIP template extracted from hip-0001.md, enriched with guidance and length recommendations derived from analyzing all existing HIPs in the repository.
+
+## Preamble format
+
+Every HIP starts with YAML frontmatter. Headers marked with `*` are optional.
+
+```yaml
+---
+hip: 9999
+title: ""
+authors: [ "Full Name <email@example.com>" ]
+created: "YYYY-MM-DD"
+type: "feature"
+status: "draft"
+---
+```
+
+### Preamble fields
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `hip` | yes | Use `9999` as placeholder on initial submission (real number assigned at merge) |
+| `title` | yes | Short descriptive title |
+| `authors` | yes | Format: `"Name <email>"` or `"Name"` (email optional) |
+| `created` | yes | RFC 3339 date (YYYY-MM-DD) |
+| `type` | yes | `feature`, `informational`, or `process` |
+| `status` | yes | Always `draft` on initial submission |
+| `helm-version`* | no | Helm version this ships with (add after implementation ships) |
+| `requires`* | no | List of HIP numbers this depends on |
+| `replaces`* | no | HIP number this obsoletes |
+| `superseded-by`* | no | HIP number that supersedes this one |
+
+### Type definitions
+
+- **feature**: proposes a new feature or implementation for a Helm project, or an interoperability standard
+- **informational**: design guidance or information for the community; non-binding
+- **process**: changes to project processes, governance, or tooling; requires org maintainer approval
+
+## Required sections with length guidance
+
+Length recommendations are based on analysis of all 26 existing HIPs. The "typical" range covers the 25th-75th percentile. These are guidelines, not rules — a complex feature HIP will naturally be longer than a simple process HIP.
+
+### Abstract
+**Typical: 25-100 words. Target: ~50 words. Max observed: 185 words.**
+
+A concise, self-contained description of what the proposal does and what problem it solves. A reader should understand the proposal's purpose without reading further. Avoid implementation details — save those for the Specification.
+
+Most accepted HIPs have abstracts well under 200 words. The hip-0001 guidance says "~200 words" but in practice shorter is better.
+
+### Motivation
+**Typical: 100-200 words. Target: ~150 words. Max observed: 488 words.**
+
+This is the most critical section for acceptance. Proposals without sufficient motivation are rejected outright. Structure around:
+
+- **Current limitations** — what can't users do today, or what is painful?
+- **Real-world impact** — concrete examples, not hypotheticals. Name the roles affected (chart authors, cluster operators, platform teams, CI/CD pipelines).
+- **Existing workarounds** — what do people do today, and why is it inadequate?
+
+Subheadings work well here (e.g., "### Current Limitations", "### Who Is Affected", "### Real-World Impact"). Most strong HIPs use them.
+
+### Rationale
+**Typical: 50-150 words. Target: ~100 words. Max observed: 4632 words (outlier).**
+
+Why this design, not just what. Cover:
+
+- Why this approach over alternatives
+- How similar problems are handled in other projects (if relevant)
+- Key tradeoffs and why they're acceptable
+- Naming decisions (if the proposal introduces new concepts or API surface)
+
+Use subheadings to separate distinct design decisions (e.g., "### Why X over Y", "### Key Tradeoffs").
+
+### Specification
+**Typical: 230-680 words. Target: ~350 words. Max observed: 1563 words.**
+
+The largest section in most HIPs. For feature HIPs, this must be detailed enough for someone else to implement. Include:
+
+- Data structures, Go types, CLI flags, API shapes
+- Usage examples (CLI invocations, YAML snippets, template examples)
+- Behavior matrix if there are multiple modes or contexts (see hip-0029 for a good example)
+- Edge cases and how they're handled
+
+For process HIPs, define concrete steps, timelines, roles, and decision criteria rather than code.
+
+### Backwards compatibility
+**Typical: 15-90 words. Target: ~30 words. Max observed: 177 words.**
+
+Often short. For purely additive changes, a sentence confirming no breakage is sufficient. For breaking changes, be explicit about:
+
+- What breaks and severity
+- Migration path
+- Whether this requires a major version bump (Helm follows SemVer)
+
+### Security implications
+**Typical: 1-40 words. Target: ~20 words. Max observed: 532 words.**
+
+Often very short for benign features ("No security implications"). For features that touch data exposure, authentication, or trust boundaries, cover:
+
+- Attack surface added
+- Data exposure risks
+- How a malicious chart or user could abuse the feature
+- Mitigations built into the design
+
+### How to teach this
+**Typical: 25-70 words. Target: ~50 words. Max observed: 569 words.**
+
+What documentation needs to change and what key patterns users should learn:
+
+- Documentation additions or modifications needed
+- The one example you'd lead with when explaining the feature
+- How it fits into concepts users already know
+
+### Reference implementation
+**Typical: 5-20 words. Target: ~15 words. Max observed: 133 words.**
+
+Usually very short. Link to a PR or describe what the implementation will involve. The implementation must be complete before the HIP can reach "final" status, but it does not need to exist when the HIP is submitted as a draft.
+
+### Rejected ideas
+**Typical: 10-100 words. Target: ~50 words. Max observed: 1171 words.**
+
+Ideas discussed and discarded, with brief explanations of why. Prevents reviewers from re-proposing the same alternatives. Use a bulleted list for multiple rejected ideas — each entry should be 1-2 sentences.
+
+### Open issues
+**Typical: 1-50 words. Target: ~15 words. Max observed: 177 words.**
+
+Unresolved questions. Fine to submit a draft HIP with open issues — they're resolved during review. Can also be empty if all questions are settled.
+
+### References
+**Typical: 10-40 words. Target: ~20 words. Max observed: 420 words.**
+
+URLs, specs, and materials referenced throughout the HIP. Use markdown link format.
+
+## Optional sections
+
+These sections appear in some existing HIPs and may be useful depending on the proposal:
+
+- **Scope** (hip-0026) — when a feature HIP is large, explicitly defining what is and isn't in scope helps focus review
+- **Implementation Plan** (hip-0026) — for complex features, a phased delivery plan with milestones
+- **Prior raised issues** (hip-0025) — links to related GitHub issues or mailing list threads that preceded the HIP
+
+## Auxiliary files
+
+Diagrams or supporting files use the naming convention: `proposal-XXX-YY.ext` (e.g., `proposal-029-01.png`), where XXX is the HIP number and YY is a serial number starting at 01.
+
+## Approval requirements
+
+- Feature and informational HIPs: at least 2 approvals from project maintainers
+- Process HIPs: at least 2 approvals from Helm org maintainers
+
+## Status lifecycle
+
+`draft` -> `accepted` -> `final` (after reference implementation is complete)
+
+Other statuses: `provisional` (accepted but needs more feedback), `deferred` (paused), `rejected`, `superseded`