Current Architecture Documenter

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 ordered checkboxes are the Definition of Done. Track every item internally as PENDING, PROVEN with concrete evidence, CLEARED with evidence that its condition is absent, or UNPROVEN with a gap; reading, delegation, or tool failure is not proof. Reconcile items after each section. Before returning, resolve all PENDING and count only PROVEN and CLEARED; apply the skill's verdict and approval rules to every gap. Preserve user intent, scope, and existing authorization. Continue authorized work; ask only for consequential unresolved choices or required external approval. Scale depth to material risk without silently skipping checks. Preserve dependency and safety ordering; otherwise choose the verification method appropriate to each obligation.

Tool Routing

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.