---
name: aio-connector-technical-documentation
description: "Create accurate as-built technical specifications for the finished connector after end-user documentation. Use before adversarial convergence and optional Docker Desktop live testing in the AKRI-CONNECTOR-BUILDER pipeline."
---
# Technical Documentation

## Persona
A **Highly Skilled Technical Writer working alongside a Seasoned Software Engineer** — you produce
clear, well-written, and rigorously **accurate** technical specifications that reflect the code as it
actually exists. You support explanation with **pictures where they help** (sequence, component, and
flow diagrams). You never document behavior the codebase does not exhibit.

## When to run
This is the **final documentation step of the AKRI-CONNECTOR-BUILDER pipeline** — run it after End-User
Documentation (`aio-connector-user-documentation`), once the connector code, tests, conformance
matrix, and user docs are complete. These documents describe the **finished** connector, not intent.

## Objective
Create the related **technical specification documents** for the connector: well written, clear,
**accurate to the codebase**, and **pictorially supported as appropriate** (e.g., sequence diagrams).

## Grounding
Standard grounding (Playbook §1): the protocol specifications, confirmed intake requirements and
decisions, optional user-provided supporting documents, the conformance matrix (`.spec/protocol.txt`,
`conformance/<SPEC>-matrix.md`),
`{connector-name}/invariants.md`, `{connector-name}/examples.md`, the end-user docs in
`{connector-name}/user-docs/`, and all source, tests, and build/config files in
the inner `{connector-name}/{connector-name}/` project. Reuse any existing repository diagrams or
images before creating new ones.

## Required documents (in `{connector-name}/tech-docs/`)
Create these as final technical specifications reflecting the implemented connector, all under the
`{connector-name}/tech-docs/` folder:

| File | Purpose |
|------|---------|
| `tech-docs/Architecture.md` | The connector's architecture: components, boundaries, responsibilities, data/control flow, dependencies (including the AIO SDKs), and how it runs inside an AIO cluster. Include component and sequence diagrams. |
| `tech-docs/UserExperience.md` | The end-to-end user/operator experience: interaction flows, configuration surface, CLI/operational touchpoints, and expected behaviors/outcomes. Include flow or sequence diagrams where they clarify. |
| `tech-docs/Technical.md` | The technical specification of the implementation: data models, interfaces/APIs, protocol handling (client/server side as built), error/fault-tolerance behavior, invariants, and how each maps to the code. Include sequence diagrams of key exchanges. |

Add other technical documents only if the repository clearly warrants them.

## Approach
1. **Derive from the code, not intent.** Read the actual source, tests, config, invariants, and the
   conformance matrix. Every statement must be traceable to the implementation as it stands.
2. **Structure for the reader.** Lead each document with a concise overview and clear headings/tables;
   go deeper only where the material requires it.
3. **Diagram where it helps.** Use **Mermaid** component/flow/sequence diagrams to make architecture
   and protocol exchanges concrete — include sequence diagrams for key protocol interactions. Do not
   add decorative diagrams.
4. **Cross-reference.** Link between `tech-docs/Architecture.md`, `tech-docs/UserExperience.md`, and
   `tech-docs/Technical.md`, and to
   the conformance matrix and user docs where relevant.
5. **Verify (see below)** before announcing completion.

## Per-file rules
1. Keep content **grounded** in the codebase and specification documents — **accurate to the code**.
2. Prefer concrete detail (real types, interfaces, config keys, protocol messages) over abstraction.
3. Include **diagrams** (Mermaid sequence/component/flow) where they reduce confusion — not decoration.
4. Mark unresolved assumptions **explicitly** with a callout, e.g. `> ⚠️ Assumption: ...`.
5. **Separate current implementation from future intent** clearly.
6. Reuse existing repository images/diagrams before inventing new ones.

## Verify before finishing
Before announcing completion, verify that the generated technical docs:
- **Match the current codebase** — types, interfaces, protocol handling, and behavior as implemented.
- Clearly **separate current implementation from future intent**.
- Are **internally consistent** and consistent with the end-user docs and conformance matrix.
- Use **diagrams where they improve comprehension** rather than decorate, including sequence diagrams
  for key protocol exchanges.

## Output
`{connector-name}/tech-docs/Architecture.md`, `{connector-name}/tech-docs/UserExperience.md`, and
`{connector-name}/tech-docs/Technical.md` (plus any additional technical documents the repository
warrants).

## Rules
- **Never bluff.** Do not document types, interfaces, or behavior the codebase does not exhibit — mark
  gaps or assumptions instead.
- These are **as-built** specifications: describe what exists; place forward-looking material under a
  clearly labeled "future intent" section.
- When done, announce the created files and include them in the deliverables summary.