K8S Report

/k8s-report — evidence → deliverables

State dir: $ARGUMENTS (defaults to the most recently touched run)

What exists to report on

cd "${CLAUDE_PROJECT_DIR:-$PWD}" && for d in .claude/k8s-contributor/state/*/*/; do [ -d "$d" ] || continue; echo "  $d"; echo "    gate:  $(jq -r '.overall // "-"' "$d/gate.json" 2>/dev/null || echo '-')"; echo "    files: $(ls "$d" 2>/dev/null | tr '\n' ' ')"; echo "    artifacts: $(ls "$d/artifacts" 2>/dev/null | tr '\n' ' ' || echo '-')"; done 2>/dev/null || echo "  (no runs yet)"

Read from the state dir: triage-report.md, plan.md, review-synthesis.md, gate.json, evidence/, and the profile. Then write four files.

1. report.md — one page

Fit it on one page. A reader should get the whole picture without opening anything else.

• Verdict — PASS or FAIL, and the one-line reason.

• Root cause — at file:line, with the causal chain from the symptom.

• The fix, in three sentences. Not a diff walkthrough.

• Evidence table — one row per gate:

  Gate	Command	Result	Log
  G2	go test ./pkg/foo -run '^TestX$' -race -count=1	pass (red→green)	evidence/G2-red.log, evidence/G2-green.log

  Build it from gate.json, not from memory. Include deferred-to-ci rows with their reason and CI job — the honest gaps matter more than the passes.

• Residual risks — what could still be wrong.

• Alternatives rejected, and why — from plan.md section 2.

• What CI will still need to prove — from the G10 checklist.

2. pr-description.md — the repo's actual template, filled

Read the template from disk. profile.pr_template gives the path (.github/PULL_REQUEST_TEMPLATE.md for the repos here). Do not reproduce a template from memory — they differ per repo and they change.

For kubernetes/kubernetes the current sections are:

#### What type of PR is this?
/kind bug

#### What this PR does / why we need it:

#### Which issue(s) this PR is related to:
Fixes #<n>

#### Special notes for your reviewer:

#### Does this PR introduce a user-facing change?
```release-note
NONE

Additional documentation e.g., KEPs, usage docs, etc.:

then `/sig <sig>` and `/cc @<owner>` lines.

Two things to get right:

- **`Fixes #<n>` is wrong for `kind/flake` and `kind/failing-test` PRs.** The
  template says so explicitly: the issue stays open to confirm the flake does
  not return. Reference the issue without the closing keyword.
- **The release note** is either a real user-facing sentence or literally
  `NONE`. Add `action required` if users must act on upgrade.

`/sig` comes from triage; `/cc` from the `OWNERS` files that govern the changed
paths (`profile.owners_reviewers`).

## 3. `issue-comment.md` — optional draft

For a triage-only run this is the verdict comment with its Prow commands
(`/triage accepted`, `/sig …`, `/kind …`, `/close`, `/remove-lifecycle stale`).
For a fix run it is usually a short "PR incoming" note, or nothing at all.

Say what it is for; do not write one just because the file is listed.

## 4. `proposed-commits.md` — unexecuted

Per commit: the file list, the full message in the repo's history style, and
the exact command.

```markdown
### Commit 1 of 2
Files: pkg/foo/bar.go
Message:
    Restore re-list after watch error in foo controller

    The controller dropped the re-list when the watch returned an error,
    leaving the cache stale until the next resync. Restore it so the
    invariant "cache converges after a watch error" holds again.

Command:
    git add pkg/foo/bar.go && git commit -m "..." -m "..."

Commit-message rules (guide/pull-requests.md): subject ≤50 chars ideally, never >72; capitalized; no trailing period; imperative mood; blank line before the body; body wrapped at 72 explaining what and why.

No GitHub keywords — fix(es|ed), close(s|d), resolve(s|d) followed by #<n> triggers do-not-merge/invalid-commit-message. And no @mentions. Fixes #<n> belongs in the PR description only.

Ending the run

Print the four file paths, then a clearly-labelled block:

=== commands you can run yourself ===
git add pkg/foo/bar.go && git commit -m "..."
gh pr create --repo kubernetes/kubernetes --title "..." --body-file .claude/k8s-contributor/state/.../pr-description.md
gh issue comment <n> --repo <owner>/<repo> --body-file .claude/k8s-contributor/state/.../issue-comment.md

These are printed, never executed. Every one is blocked by a deny rule and by guard-destructive.sh. Do not offer to run them as the next step — print them and stop. Wait for the user to ask.