From 07ea5cc65a0410de6005d429078a7f2eadff34c2 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sun, 5 Jul 2026 14:02:27 +0200 Subject: [PATCH 1/3] feat(ai-assistant): make upstream research and product debugging the empty-backlog motion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Maintainer direction 2026-07-05: when no substantive issue is startable, the run researches upstream state of the art (Headlamp, ArgoCD, FluxCD, Kubernetes, and each product's other key dependencies) and debugs the products hands-on, filing every finding as a well-formed issue — so the backlog restocks itself and ksail/the platform track upstream capabilities. Seeded by the cross-repo Headlamp-parity epic ksail#5827 + platform#2496. Co-Authored-By: Claude Fable 5 --- .claude/skills/portfolio-maintenance/SKILL.md | 8 +++++++ .claude/skills/product-engineering/SKILL.md | 24 +++++++++++++++++++ AGENTS.md | 12 ++++++++++ 3 files changed, 44 insertions(+) diff --git a/.claude/skills/portfolio-maintenance/SKILL.md b/.claude/skills/portfolio-maintenance/SKILL.md index 334a7ee6..58311e3c 100644 --- a/.claude/skills/portfolio-maintenance/SKILL.md +++ b/.claude/skills/portfolio-maintenance/SKILL.md @@ -217,6 +217,14 @@ backlog. Use the [`product-engineering`](../product-engineering/SKILL.md) skill; per-product docs + the site (whose recurring slice — Site QA / Content Sync / Content Review — is the monorepo card). +10. **Continuous upstream research & product debugging** — the backstop when rungs 6-9 come up empty: + research upstream state of the art (Headlamp, ArgoCD, FluxCD, Kubernetes, and each product's other + key dependencies) and exercise the product hands-on to surface bugs, friction, and feature/quality/ + performance/reliability/UI/UX gaps — every finding filed as a well-formed issue that restocks the + queue rung 6 drains (procedure: [`product-engineering`](../product-engineering/SKILL.md) §9; + maintainer direction 2026-07-05, seeding epic ksail#5827). An empty backlog is a trigger for + research, never for a survey-and-exit run. + **Self-improvement** (≈weekly, orthogonal) — distil logged `learnings` into a guard-railed draft PR that improves your own definition (the [`self-improvement`](../self-improvement/SKILL.md) skill). diff --git a/.claude/skills/product-engineering/SKILL.md b/.claude/skills/product-engineering/SKILL.md index c0a8b71a..5a1aaef8 100644 --- a/.claude/skills/product-engineering/SKILL.md +++ b/.claude/skills/product-engineering/SKILL.md @@ -182,6 +182,30 @@ at once** — the highest-leverage advance work is often cross-cutting (contract form (`AGENTS.md`, `gh`-installable skills); reserve Claude-native primitives for Claude-specific power. This is what keeps a Claude → Copilot/ChatGPT switch painless. +## 9. Continuous upstream research & product debugging (the empty-backlog motion) +Sections 1-8 drain and shape a backlog that already exists. **When the actionable backlog runs empty or +thin** (no startable substantive issue after the *Issue-driven* skip test) — and additionally as an +input to every §1 strategy review — **restock it** instead of exiting (contract → *Enhancement work*; +maintainer direction 2026-07-05): +- **Upstream research.** For the product's key dependencies and comparable tools, read what shipped + since the last research pass — release notes, changelogs, roadmaps, headline features. For + ksail/platform that means **Headlamp, ArgoCD, FluxCD, Kubernetes**, and the other controllers and + tooling they build on (Cilium, Talos, Crossplane, Kubescape, …); for other products, their own + upstream set. The question per finding: *does this create a gap, an opportunity, or an obligation for + our product?* (Seeding cross-repo epic: ksail#5827 — Headlamp feature parity in the KSail web UI, + plugin absorption, and Headlamp retirement from the platform, with platform#2496 as the gated + platform half.) +- **Product debugging.** Exercise the product hands-on like a user (CLI flows, web UI, docs + walk-throughs, a real workload on the local cluster where the once-a-day cluster budget allows) and + hunt friction: bugs, rough edges, missing affordances, slow paths, flaky behaviour, confusing UX. +- **Output = well-formed issues, never ad-hoc PRs.** Each finding becomes an issue (*problem → + proposed direction → rough size*, labelled; `roadmap` for theme-sized findings) per the contract's + *Issue-driven* rule, joining the oldest-first queue. Research restocks the queue — it never displaces + startable substantive work. +- **Cursor & cadence.** Record a per-product `last_research` cursor in native memory (pointer only). + Dedupe against existing issues before filing; a research pass that files nothing new still updates + the cursor and notes what was checked. + ## Per-product notes (where "advance" means different things) - **ksail** (Go CLI): features/UX, coverage on command/reconcile paths, `-bench` on hot loops; weekly E2E + reliability and the Monthly Strategy are its heavy cadence (see its card/`AGENTS.md`). diff --git a/AGENTS.md b/AGENTS.md index 1a368b5d..3b8709b7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -451,6 +451,18 @@ standing substitute** for moving the real backlog: generated-file list, validate step, or convention updates **every** agent file that referenced it **in the same PR** — never let `AGENTS.md`, a `.claude/` card, and a `.github/instructions/` file drift apart. On the **docs cadence**, fold an agent-file freshness pass into the per-product docs pass (oldest first). +- **Continuous upstream research & product debugging** — when the actionable backlog runs empty or thin + (no startable substantive issue), the run does NOT survey-and-exit: it **restocks the backlog** by + (a) **researching upstream state of the art** — new features and capabilities in each product's key + dependencies and comparable tools (for ksail/platform: Headlamp, ArgoCD, FluxCD, Kubernetes, and the + other controllers/tooling they build on — release notes, changelogs, roadmaps) — and (b) **hands-on + product debugging** — exercising the product like a user to surface bugs, friction, and gaps in + features, code quality, performance, reliability, UI and UX. Every finding is converted into a + **well-formed issue** (*problem → proposed direction → rough size*, labelled) per *Issue-driven*, so + ksail and the platform stay at parity with upstream state-of-the-art capabilities (maintainer + direction 2026-07-05; seeding cross-repo epic: ksail#5827 Headlamp-parity). Research restocks the + queue — it never displaces startable substantive work, and it also runs on the strategy-review + cadence as an input to each product's roadmap refresh. The [`product-engineering`](.claude/skills/product-engineering/SKILL.md) skill is the how-to. All of it is **root-cause, validated, draft-PR** work under the guardrails below — advancing a product is never licence to skip tests, weaken a safety rule, or hand-edit generated files. Respect each repo's From 3df30542d335d36f463b3296d62d68bd6acc8a39 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sun, 5 Jul 2026 14:10:52 +0200 Subject: [PATCH 2/3] docs(ai-assistant): name the last_research cursor in the canonical state model Co-Authored-By: Claude Fable 5 --- .claude/skills/portfolio-maintenance/SKILL.md | 6 ++++-- AGENTS.md | 3 ++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/.claude/skills/portfolio-maintenance/SKILL.md b/.claude/skills/portfolio-maintenance/SKILL.md index 58311e3c..3cef7191 100644 --- a/.claude/skills/portfolio-maintenance/SKILL.md +++ b/.claude/skills/portfolio-maintenance/SKILL.md @@ -105,7 +105,8 @@ instruction. The returned digest (operate + advance signals, products-with-no-signal omitted) is your survey result. **Overlay your native-memory cadence cursors yourself** — each product's `last_worked`, -`roadmap` (last strategy review + current theme), `weekly` timestamps, `needs_attention`, and the +`roadmap` (last strategy review + current theme), `last_research`, `weekly` timestamps, +`needs_attention`, and the CI/link caches — since the surveyor reads only live GitHub, not memory. ~Monthly, also do the **holistic review** (contract *Holistic review*): scan the suite for generic patterns to extract into the shared libraries (`devantler-tech/actions`, `reusable-workflows`, `skills`, `plugins`). @@ -288,7 +289,8 @@ For each selected product: Suggested files (markdown, organise as works best — not a rigid schema): - `portfolio-status.md` — `last_run`, `rotation_cursor`, and per product: `last_worked`, `weekly` - timestamps, roadmap cursor (last strategy review + current theme), `last_docs_pass` (the docs-pass + timestamps, roadmap cursor (last strategy review + current theme), `last_research` (the + upstream-research/product-debugging cursor — `product-engineering` §9), `last_docs_pass` (the docs-pass cadence cursor that drives the "oldest first" docs rotation — see *Cadence gates*), open `needs_attention`. - `caches.md` — CI-investigation cache (signature/PR/run-ids/dates), `unfixable_links` / `watch_links` diff --git a/AGENTS.md b/AGENTS.md index 3b8709b7..72b6f28b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -677,7 +677,8 @@ step: tool** (the `/memories` directory; in Claude Code, the project's `memory/` dir with its `MEMORY.md` index). **View it at the start of every run** and treat it as the single source of truth for cross-run orchestration: rotation cursor, per-product `last_worked` / `weekly` / roadmap cursor - (last strategy review + current theme) / open `needs_attention`, the CI & link investigation caches, + (last strategy review + current theme) / `last_research` (the upstream-research/product-debugging + cursor — see *Enhancement work*) / open `needs_attention`, the CI & link investigation caches, recent run notes, and self-improvement `learnings`. Keep it **coherent and organised** (a small set of well-named files, not one per fact; prune stale entries; keep `MEMORY.md` a true index); don't let it sprawl. **`MEMORY.md` is one line per entry — never more.** It is an *index*: each bullet is a From 90a928d4a5f8704715f982a6ac6476a991c31143 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sun, 5 Jul 2026 14:16:17 +0200 Subject: [PATCH 3/3] docs(ai-assistant): persist last_research in the run write-back checklist Co-Authored-By: Claude Fable 5 --- .claude/skills/portfolio-maintenance/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/portfolio-maintenance/SKILL.md b/.claude/skills/portfolio-maintenance/SKILL.md index 3cef7191..bbb8865b 100644 --- a/.claude/skills/portfolio-maintenance/SKILL.md +++ b/.claude/skills/portfolio-maintenance/SKILL.md @@ -276,7 +276,7 @@ For each selected product: ## 4. Always: update native memory + one consolidated report - **Native memory** (the single source of truth — your runtime's memory tool; never costs a PR): write back what changed so the next run picks up cleanly — `last_run`, `rotation_cursor`, each touched - product's `last_worked`/`weekly`/roadmap cursor/`needs_attention`, the CI & link caches (prune CI + product's `last_worked`/`weekly`/roadmap cursor/`last_research`/`needs_attention`, the CI & link caches (prune CI entries >7 days), recent run notes, and any new `learnings`. Keep memory **coherent and organised**: a small set of well-named files (e.g. `portfolio-status.md`, `caches.md`, `learnings.md`, plus `feedback_*.md`) with `MEMORY.md` as a true index; **edit in place and prune stale content** rather