Component Documentation

Platform Component Documentation

Act as a senior platform engineer and technical writer. The output must let four different readers succeed: a new engineer learning the component, an operator during an incident, a security reviewer assessing exposure, and an auditor tracing the architecture.

The section structure — core sections plus the packs that apply to this component type — is in references/document-template.md. Read it before writing. This file describes how to get the facts that fill it.

The one rule that matters

Never write a fact you have not read in a file or observed in a running system. The template asks for things many components simply do not have (a WAF, an RPO/RTO, retention limits, named owners). The failure mode of this skill is a confident, well-formatted document full of plausible inventions — which is worse than no document, because it will be trusted during an incident and cited in an audit.

When a fact is not established, write one of these verbatim instead of guessing:

• **Not present** / **Niet aanwezig** — verified absent; say where you looked.
• **Unknown** / **Onbekend** — not verifiable from the sources available.
• **Unknown — ask <team/role>** — knowable, but not from code.

A section that is honestly half unknown is a working backlog. An invented section is a liability. Collect every unknown into the Risks and technical debt section as well.

Step 0 — Scope and classify

Establish two things before searching.

Which component? If the user named one, use it. If they asked for "the repo" or were vague, list the candidates from the component map below and ask which one — do not silently document all of them. Documenting several means one document per component, never one giant file.

Which family? The family decides which section packs apply. Classify by what the component does, not by which directory it sits in:

A component can span two families. The API gateway is edge and a cluster service; document both packs rather than picking one.

Step 1 — Locate the evidence

Work from code first; the repository is the source of truth for intent. Use a live system only to confirm what code cannot tell you (actual replica counts, real issued certificates, load balancer IPs, current retention).

Always:

Then the family-specific sweep:

Live checks, when a cluster is reachable and the user has authorised it:

kubectl -n <ns> get all
kubectl -n <ns> get pdb,networkpolicy,servicemonitor
kubectl get certificate,clusterissuer -A
helm -n <ns> get values <release>          # what is actually deployed, not what is in git

Step 2 — Reconcile intent against reality

Note every place where the code and the running system disagree, and every reference that points at something that no longer exists — a renewal job naming a deleted Certificate, a scrape job for a removed exporter, a DNS record without a backing host, a values key the chart no longer reads. These mismatches are the highest-value content in the whole document: they are exactly what nobody remembers and what breaks at 03:00. Put them in Risks and technical debt with the file and line.

Two recurring traps worth checking explicitly:

• A Helm values key that the chart silently ignores because it is nested wrong or was renamed upstream. Verify keys against helm show values <chart> --version <pinned> before trusting them; a wrong key does not error, it just does nothing.
• A component that looks monitored but is not — generic per-namespace alerts firing while the component's own signals (request rate, queue depth, ingestion errors, certificate expiry) are scraped by nothing.

Also record the things that look wrong but are correct, with the reason. A future reader will otherwise "fix" them.

Step 3 — Write

Follow references/document-template.md: every core section, plus the packs for this component's family. Standards:

• Why before how. Every configuration choice gets a sentence of rationale. If the rationale is unknown, say so — that is a finding.
• Tables over prose for anything enumerable. Prose only for reasoning.
• One Mermaid diagram of the real components, and a flow diagram (request path, data path, or dependency chain, whichever fits the family). No idealised boxes that do not exist; draw absent-but-expected hops as dashed and label them as absent.
• Expand every acronym on first use (TLS, ACME, CA, CRD, PDB, RBAC, WAF, RPO, RTO, SPOF).
• Assume zero prior knowledge of this environment, but competence in Kubernetes.
• Link to files, do not paste them. Relative Markdown links from the document's own location; verify every link and heading anchor resolves before finishing.
• Call out security and operational risk explicitly, in its own sentence, not softened.
• Match the language of the surrounding documentation — do not introduce a second language into a repository that already picked one.
• Run the repository's Markdown linter if there is one, or at least keep table delimiter rows and fenced-code languages consistent with neighbouring documents.

Step 4 — Place it and keep it alive

One canonical location per component. If the component already has a document, update it — never create a second one next to it.

• A component with its own chart directory: that directory's README.md.
• A cross-cutting subject that spans charts and pipelines (ingress and TLS, the whole observability stack): docs/<SUBJECT>.md.

Add a pointer from the repository README, and from the chart README to the docs/ file when both exist. End the document with the instruction that changes to this component update the document in the same pull request — documentation that is not updated with the change becomes a second source of truth, which is worse than one.

Repository-specific knowledge

A per-repository component map (directory → family → namespace → existing doc) speeds this skill up considerably, but it belongs in that repository, not here. Look for it in this order, and verify whatever you find against the tree before relying on it:

1. A project skill at .claude/skills/<repo>-components/SKILL.md holding that table.
2. A "Components" section in the repository's CLAUDE.md.
3. Neither: derive the map from the tree in Step 1, then offer to write it to the first location.