diff --git a/.claude/skills/portfolio-maintenance/SKILL.md b/.claude/skills/portfolio-maintenance/SKILL.md index 334a7ee6..bbb8865b 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`). @@ -217,6 +218,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). @@ -267,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 @@ -280,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/.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..72b6f28b 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 @@ -665,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