Promote k3s triage trees and trap docs into Ops investigation skills #704

New issue

Closed

opened 2026-07-31 08:54:01 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-07-31 08:54:01 +00:00

Owner

Outcome

Turn the symptom-driven k3s deployment triage material into discoverable Ops investigation skills while retaining architecture and configuration explanation as durable docs.

Depends on the canonical provider layout in #702

Source material

Audit and consolidate the operator procedures currently spread across:

docs/k3s-deploy-notes-triage-tree.md
docs/k3s-deploy-notes-triage-tree-runner.md
docs/k3s-deploy-notes-triage-tree-tailscale-proxy.md
docs/k3s-deploy-notes-traps.md
docs/k3s-deploy-notes-traps-host.md
docs/k3s-deploy-notes-traps-caddy.md
docs/k3s-deploy-notes-traps-runner.md
docs/k3s-deploy-notes-traps-forgejo.md
docs/k3s-deploy-notes-traps-publish-image.md
docs/k3s-deploy-notes-traps-tailscale-proxy.md
docs/k3s-deploy-notes-traps-terraform.md

Skill shape

Create the smallest useful router and focused investigation skills for the actual symptom families. Do not create one skill per docs file.
Cover workload startup failures, image pulls, ExternalSecret or certificate failures, host and Caddy routing, Forgejo runner failures, publish-image failures, and Tailscale proxy failures.
Reuse the existing pod-eviction and k3s-upgrade skills rather than copying their procedures.
Keep descriptions focused on fuzzy symptom discovery and aliases. Move detailed branching into references.
Preserve the cluster ownership boundary. Infrastructure skills diagnose cluster and host behavior. Deploy skills remain authoritative for service rollout configuration.
Separate approved read-only observation from mutations, rollout, cleanup, and secret handling.
Name the evidence and stop condition for every branch before recommending a change.
Keep docs/k3s-deploy-notes.md as the top-level architecture and deployment reference, with operator branches routed into skills.
Remove duplicated procedures and repair all navigation links.

Acceptance

Common prompts such as pod crashloop, image pull failure, ExternalSecret not syncing, runner job stuck, publish image failure, Caddy route broken, and Tailscale proxy unreachable each discover a clear skill.
Each symptom has one authoritative investigation branch.
Existing pod-eviction and k3s-upgrade skills remain peers with explicit routing rather than duplicated content.
Skill references preserve the known traps and concrete evidence checks from the source docs.
The skills do not grant live mutation authority or expose secret values.
Architecture, topology, and configuration-contract material that remains in docs is not copied into skill bodies.
docs/FEATURES.md reflects any materially reshaped operator capability.
Skill validation, dead-link checks, and pre-commit run --all-files pass.

## Outcome Turn the symptom-driven k3s deployment triage material into discoverable Ops investigation skills while retaining architecture and configuration explanation as durable docs. Depends on the canonical provider layout in https://forgejo.coilysiren.me/coilyco-flight-deck/infrastructure/issues/702 ## Source material Audit and consolidate the operator procedures currently spread across: * `docs/k3s-deploy-notes-triage-tree.md` * `docs/k3s-deploy-notes-triage-tree-runner.md` * `docs/k3s-deploy-notes-triage-tree-tailscale-proxy.md` * `docs/k3s-deploy-notes-traps.md` * `docs/k3s-deploy-notes-traps-host.md` * `docs/k3s-deploy-notes-traps-caddy.md` * `docs/k3s-deploy-notes-traps-runner.md` * `docs/k3s-deploy-notes-traps-forgejo.md` * `docs/k3s-deploy-notes-traps-publish-image.md` * `docs/k3s-deploy-notes-traps-tailscale-proxy.md` * `docs/k3s-deploy-notes-traps-terraform.md` ## Skill shape * Create the smallest useful router and focused investigation skills for the actual symptom families. Do not create one skill per docs file. * Cover workload startup failures, image pulls, ExternalSecret or certificate failures, host and Caddy routing, Forgejo runner failures, publish-image failures, and Tailscale proxy failures. * Reuse the existing pod-eviction and k3s-upgrade skills rather than copying their procedures. * Keep descriptions focused on fuzzy symptom discovery and aliases. Move detailed branching into references. * Preserve the cluster ownership boundary. Infrastructure skills diagnose cluster and host behavior. Deploy skills remain authoritative for service rollout configuration. * Separate approved read-only observation from mutations, rollout, cleanup, and secret handling. * Name the evidence and stop condition for every branch before recommending a change. * Keep `docs/k3s-deploy-notes.md` as the top-level architecture and deployment reference, with operator branches routed into skills. * Remove duplicated procedures and repair all navigation links. ## Acceptance * Common prompts such as pod crashloop, image pull failure, ExternalSecret not syncing, runner job stuck, publish image failure, Caddy route broken, and Tailscale proxy unreachable each discover a clear skill. * Each symptom has one authoritative investigation branch. * Existing pod-eviction and k3s-upgrade skills remain peers with explicit routing rather than duplicated content. * Skill references preserve the known traps and concrete evidence checks from the source docs. * The skills do not grant live mutation authority or expose secret values. * Architecture, topology, and configuration-contract material that remains in docs is not copied into skill bodies. * docs/FEATURES.md reflects any materially reshaped operator capability. * Skill validation, dead-link checks, and pre-commit run --all-files pass.

coilyco-ops referenced this issue from coilyco-flight-deck/agent-compose

2026-07-31 08:54:16 +00:00

Add role-scoped skill providers to native and staged bundles #168

coilyco-ops referenced this issue

2026-07-31 08:54:22 +00:00

Make infrastructure a canonical Agent Compose skill provider #702

coilyco-ops referenced this issue from a commit

2026-07-31 09:40:06 +00:00

docs: promote k3s triage into ops skills

coilyco-ops closed this issue

2026-07-31 09:40:06 +00:00