Update to incident.io

{
  "description": "Answer questions about how the organisation builds, deploys, and runs its software — what a system is, where it runs, what it depends on, and the real names of things (cloud projects, clusters, namespaces, hostnames, buckets) — from architecture docs wherever they live. Use when asked \"how does X run\", \"what is Y\", \"where does Z live\", or when grounding a component before debugging it.\n",
  "included_files": [
    {
      "relative_path": "references/where-docs-live.md",
      "size_in_bytes": 5782
    }
  ],
  "name": "architecture",
  "skill_md_contents": "---\nname: architecture\ndescription: >\n  Answer questions about how the organisation builds, deploys, and runs its software —\n  what a system is, where it runs, what it depends on, and the real names of things\n  (cloud projects, clusters, namespaces, hostnames, buckets) — from architecture docs\n  wherever they live. Use when asked \"how does X run\", \"what is Y\", \"where does Z live\",\n  or when grounding a component before debugging it.\nargument-hint: \"<an estate question to answer>\"\n---\n\n# Architecture\n\nArchitecture docs describe what systems *are*: where they run, what they depend on, and\nthe real names of things. They pair with runbooks — runbooks own *procedures* (how to\ndiagnose and fix a failure), architecture owns *facts* (what the component is in the\nfirst place). This skill answers estate questions (the estate: everything you run and\nwhere) from those docs, cited — never from general knowledge. General knowledge is\nexactly what these docs exist to override: a team's setup differs from defaults in\nprecisely the ways worth writing down.\n\n## Where you are running\n\nYou are a coding agent with the incident.io plugin installed.\n\n- **Before you start:** load the `extensions` skill and have it map the estate — which\n  plugins are registered, where each lives, and their sync state. Skipping it doesn't\n  fail loudly. It just means you searched the local half of the estate and reported it\n  as the whole.\n- **Where to search:** the four places in\n  [where-docs-live.md](references/where-docs-live.md), in its order. Read it before\n  searching, even when you think you know where the docs are.\n- **Where live config lives:** the workspace.\n- **When the docs have a gap:** if the user wants it filled now, that's the\n  `architecture-author` skill.\n- **When the question is really \"how do I fix this failure\":** hand over to the\n  `runbooks` skill. Its Find job owns routing a symptom to its runbook.\n- **How to reply:** in the voice the `talking-to-the-user` skill sets — lead with the\n  answer, be concise, one next step where there is one.\n\n## 1. Pin the subject\n\nReduce the question to the system or identifier it is about: a service name, a\nhostname, a cluster, a bucket, a deployment. Keep both the literal identifier (for\nkeyword search and grep) and the question phrasing (for semantic search).\n\n## 2. Search\n\nSearch the places above, in their order. Start each corpus at its README — a\nwell-formed corpus has a \"Where do I look?\" routing table that resolves most questions\nin one hop. Do not grep the tree before trying the map; the map exists so one hop finds\nthe owning file. Grep only when the map misses. Document search results carry a source\nprovider and generated tags; architecture-shaped documents describe systems and\ninfrastructure rather than procedures.\n\n## 3. Answer from the owning doc\n\n- **Quote identifiers verbatim** — project IDs, cluster and pool names, hostnames,\n  subscription names. A paraphrased identifier is worse than none.\n- **Cite the doc** each fact came from, and the authoritative config repo where the\n  doc names one.\n- **Respect what the docs deliberately do not hold.** Values that churn — replica\n  counts, resource limits, machine types, current flag state — are pointed at, not\n  copied. Answer with where the current value lives, not a number the docs never\n  promised. If the live config above holds that value, read it and say where it came\n  from.\n- **Keep it short.** Most questions resolve to a few sentences and one or two doc\n  references.\n\n## 4. When the docs do not cover it\n\nFirst make sure that is what happened. A place you couldn't reach is not a place with no\ndocs, and reporting an unreachable corpus as a missing one sends someone to write a\ndocument that already exists. Name what you couldn't search.\n\nOnce it's genuinely a gap, say so explicitly. Answer from other evidence when you have\nit — deploy manifests, service definitions, config, a connected system's own listing —\nclearly labelled with where it came from, not the docs. Never silently substitute general\nknowledge for a missing doc.\n\nThen note the gap as a curation candidate: a question the docs could not answer is a\nsection waiting to be written. Handle it as \"Where you are running\" says.\n\n## Rules\n\n- Read-only, always: this skill explains; it never mutates, flips flags, or runs\n  commands that change state.\n- Route, don't absorb: if the question is really \"how do I fix this failure\", ground\n  the component here, then hand over as \"Where you are running\" says.\n\n## What this skill is not for\n\nWriting or maintaining architecture docs, diagnosis and fixes (the runbook that owns the\nfailure), current runtime state (replica counts, flag values — the docs point at where\nthose live), and product or code-level documentation (API references, user guides).\n"
}