/ln-22-current-architecture-documenter

name: ln-22-current-architecture-documenter
description: "Documents current architecture from implementation evidence; does not propose a target or audit fitness."

Current Architecture Documenter

**Goal:** Produce a trustworthy snapshot of the architecture implemented in the checked-out repository. Document what exists and how it behaves; do not score it, prescribe a target architecture, repair code, or turn intended diagrams into facts.

**Execution contract:** The checklist defines completion. Track each item internally as `PENDING`, `PROVEN` with evidence, `CLEARED` with evidence its condition is absent, or `UNPROVEN` with a gap; reading, delegation, or tool failure is not proof. Reconcile after each section. Before returning, resolve all `PENDING`, count only `PROVEN` and `CLEARED`, and apply verdict and approval rules to every gap. Preserve intent, scope, and existing authorization. Continue authorized work; ask only for consequential unresolved choices or required external approval. Scale depth to material risk without skipping checks. Preserve dependency and safety order; otherwise choose an appropriate verification method. Accept equivalent user or repository evidence; no other skill, named artifact, or complete lifecycle is required. Preserve source requirement and decision IDs. Bind reused evidence to relevant source versions, dirty changes, configuration, and environment; invalidate only affected claims. On continuation, reconcile task, authorization, current state, and unresolved evidence. For long work, return a compact continuation record or update an already authorized artifact; read-only skills do not persist it. Distinguish artifact readiness, verified behavior, and external-action authority. Prepare authorized work before required approval. If blocked by an instruction, cite its exact source and unresolved boundary; do not invent approval gates from caution.

Tool Routing

| Need | Preferred capability | Fallback | |---|---|---| | Snapshot identity and worktree state | Git status, branch, remote, and HEAD | Record the supplied snapshot as `UNVERIFIED` | | Structure and configuration | Native listing, search, manifests, and direct file reads | Narrow manual inspection | | Symbols, dependencies, and consumers | Language intelligence or resolved dependency tooling | Search definitions, registrations, imports, and callers | | Runtime and deployment topology | Entrypoints, IaC, containers, CI, configuration, and runtime evidence | Mark deployment relationships `UNKNOWN` | | Document mutation | Minimal patch to the approved architecture document | Return `BLOCKED` if no writable path is authorized |

Prefer local evidence over remote repository state. A path, diagram, or naming convention is a lead until executable wiring or an authoritative contract confirms it.

Artifact Rules

• Reuse a clear current-state architecture document; otherwise use `docs/architecture/current-state.md`.
• Anchor the document to remote, branch, HEAD, worktree state, and observation date.
• Cite material claims with file paths, symbols, commands, or configuration keys.
• Label claims `OBSERVED`, `DOCUMENTED`, `INFERRED`, or `UNKNOWN`.
• Separate actual structure from intended target design and from audit findings.
• Map the declared system scope at a coarse level first, then deepen only what explains its critical behavior; do not expand a bounded request into a repository-wide inventory.
• Prefer responsibility-oriented descriptions over exhaustive file inventories.
• Record the evidence cutoff so readers can distinguish uninspected scope from genuine absence.
• Keep volatile counts or inventories only when they affect architectural understanding.

Checklist

1. Establish the Documentation Contract

• [ ] Resolve repository scope, intended readers, approved destination, required depth, and language.
• [ ] Read repository instructions and record snapshot identity plus dirty-worktree limitations.
• [ ] Search for existing current-state, baseline, target-design, decision, diagram, and deployment artifacts.
• [ ] Reuse an unambiguous current-state document or select the default path without duplicating project knowledge.
• [ ] Keep the run read-only except for the approved architecture document.

2. Map the System Breadth

• [ ] Identify languages, frameworks, package roots, generated surfaces, and canonical build or run commands from manifests and CI.
• [ ] Identify users, external systems, entrypoints, applications, services, processes, workers, scheduled jobs, and deployment units.
• [ ] Map major domains or modules, responsibilities, ownership, and dependency direction.
• [ ] Map data stores, caches, queues, files, external APIs, schemas, and systems of record.
• [ ] Record public interfaces, runtime discovery, registration, configuration composition, and environment boundaries.
• [ ] Record build, deploy, scale, and failure boundaries without inferring independence from directory names.

3. Trace Critical Behavior

• [ ] Select representative critical flows based on business importance and architectural reach.
• [ ] Trace each flow from actor or trigger through entrypoint, runtime coordination, domain behavior, persistence or integration, and observable outcome.
• [ ] Record synchronous and asynchronous hops, transaction ownership, consistency, retry, timeout, idempotency, and error propagation where evidenced.
• [ ] Describe deployment, startup, shutdown, health, observability, and recovery paths visible from repository evidence.
• [ ] Deepen only subsystems whose complexity or uncertainty affects architectural understanding; keep ordinary implementation detail out of the architecture document.

4. Write the Current-State Artifact

• [ ] Write snapshot identity, system context, component inventory, responsibilities, dependency and data flow, runtime topology, critical flows, deployment, ownership, and evidence index.
• [ ] Include the minimum useful diagrams