Knowledge

A knowledge artifact is what remains after an incident is over: the problem, the solution, and the lessons — attached to the verified events that produced them. It is the difference between a team that solves a problem once and a team that solves it every eighteen months because nobody remembers the last time.

Knowledge in Pulse is derived, not authored in a vacuum. When a BLOCK is resolved by an UNLOCK, the pair carries everything a write-up needs: what broke, what the impact was, what was tried, what actually worked, and the proof that the fix shipped. The knowledge artifact is that record, distilled and given a permanent home.

Knowledge exists so that hard-won understanding stops being disposable. Every organization has a shared memory that decays: the person who understood the pooling issue left, the postmortem doc is in a folder nobody opens, and the runbook was accurate two migrations ago. Pulse makes the write-up a byproduct of the resolution rather than a chore that follows it — and anchors it to events that prove it happened.

Documentation that is a separate task does not get done. That is not a discipline problem; it is a structural one. The moment the incident is over, the incentive to write it up collapses, and the person best placed to do it is the most exhausted and the least available.

So we tied knowledge to the thing that does get done: closing the incident. To resolve a BLOCK you must record an UNLOCK, and an UNLOCK requires you to state what fixed it. That statement — made while the fix is fresh, by the person who made it, attached to a proof that it shipped — is the artifact. The write-up is not extra work; it is the resolution, kept.

• Derivation — artifacts come from resolved incidents. The source events are part of the artifact, not a citation bolted onto it.
• Permanence — an artifact outlives the project, the organization and the author. It stays reachable and stays attributed.
• Attribution — the engineers who worked the incident are credited on the artifact, and the artifact contributes to their Resolution and Collaboration dimensions.
• Discoverability — artifacts are indexed and searchable. The point is that someone hitting the same failure finds yours.
• Standalone knowledge — you can also author a KNOWLEDGE event directly in the Engineering Workspace, for understanding that did not come from an incident. It is held to the same structure.

A BLOCK opens a room: a working space attached to the incident where engineers contribute findings, dead ends and fixes while the problem is live. The room is not a chat window that gets cleared — it is part of the record, and it is the raw material the artifact is distilled from. This is why working an incident in the open produces better knowledge than working it in a DM and writing it up afterwards.

1. A BLOCK is recorded. A room opens with it.
2. Engineers work the problem in the room. Findings, attempts and dead ends are attached to the incident.
3. The fix ships and is captured as a verified PUSH.
4. An UNLOCK is recorded, linked to the BLOCK, stating what resolved it.
5. Pulse derives a knowledge artifact from the resolved pair — problem, solution, lessons, and the proofs behind them.
6. The artifact is published to the knowledge index, credited to the engineers who worked it, and surfaced to anyone who searches the failure.

  BLOCK ──────▶  ROOM  ──────▶  UNLOCK  ──────▶  KNOWLEDGE ARTIFACT
  recorded       findings        resolves the       derived, permanent,
  while you      dead ends       BLOCK, states      credited, searchable
  are still      the fix         what worked
  in it              │                 │                     │
                     │                 │                     ├── Problem
                     └── raw material ─┴────────────────────▶├── Solution
                                                             ├── Lessons (incl. dead ends)
   PUSH ─────────────────────────────────────────────────────┴── Proofs
   the fix ships and captures itself

  The write-up is not a task that follows the incident. It IS the resolution, kept —
  which is why it gets done, and why it is accurate.

1. Record the BLOCK as soon as you know you have a real problem.
2. Work it in the room, in the open, including the things that did not work.
3. Resolve it with an UNLOCK that says what actually fixed it and why.
4. Read the derived artifact and sharpen the lessons while the incident is fresh.
5. Search knowledge before you debug the next incident. The most valuable artifact is the one that saves you the outage.

The atlas-gateway pooling incident, once resolved, produced this artifact automatically from the BLOCK/UNLOCK pair.

{
  "id": "know_pool_exhaustion",
  "title": "Connection-pool exhaustion under rolling deploys",
  "problem": "Each new replica opened a full Postgres pool before the outgoing replicas drained. During a rolling deploy the gateway briefly held 2x its steady-state connections, hit max_connections, and returned 503s for roughly 90 seconds per deploy.",
  "solution": "Replicas were moved behind PgBouncer in transaction mode, so pool size is decoupled from replica count. Readiness for a new replica is now gated on the old replica reporting drained, which removes the overlap window entirely.",
  "lessons": [
    "Connection count is a function of replica count during a deploy, not of steady-state load. Size for the overlap, not the average.",
    "Raising max_connections was tried first and made it worse — more accepted connections meant more contention and slower drains.",
    "The failure was invisible in request-rate dashboards. It only showed up in pool-wait latency."
  ],
  "derivedFrom": ["evt_atlas_pool_block", "evt_atlas_pool_unlock"],
  "contributors": ["@aria"],
  "verified": true
}

# Find it before you debug it
pulse logs --project atlas-gateway --kind BLOCK

• Record the dead ends. What did not work is often more useful than what did, because it is what the next engineer will try first.
• Write the solution in terms of the system, not the change. 'Moved to PgBouncer in transaction mode so pool size decouples from replica count' teaches; 'updated the helm chart' does not.
• Name artifacts after the failure, not the fix. People search for the symptom they are staring at.
• Search knowledge at the start of an incident, not the end.
• Keep the room open while you work. Findings recorded live are the raw material; findings reconstructed afterwards are a summary.

• Resolving a BLOCK with an UNLOCK that just says 'fixed'. It closes the incident and produces an artifact that teaches nobody anything.
• Working the incident in a private thread and pasting a conclusion into the UNLOCK. The conclusion survives; the reasoning that made it credible does not.
• Treating artifacts as documentation to be maintained. They are a record of a moment, not a living wiki page — if the system changes, the next incident produces the next artifact.
• Authoring a standalone KNOWLEDGE event to describe work that never happened. Unverified knowledge is visibly unverified, and it carries almost no weight.

• Artifacts are append-only like everything else. A correction is a new artifact linked to the old one; the original stays.
• A masked incident still produces an artifact. The lesson is publishable even when the system detail is not — see Privacy Mask.
• Knowledge contributes to the Resolution and Collaboration dimensions of Build Cred for everyone who worked the room, not just the person who typed the UNLOCK.
• Artifacts survive project archival and organization deletion. That is the entire point of making them derived and permanent.