architecture-and-decisionslisted

Create an architecture and decision walkthrough that explains how a software project fits together and WHY each significant choice was made, with the alternatives, the trade-offs, and the failure modes. Takes a reader from "can use it" to "understands it well enough to change or extend it safely." Produces Markdown (repo-first) with C4-style diagrams and a decision treatment for every important choice. Use this whenever the user wants an architecture doc, design doc, technical deep-dive, decision record narrative, "why is it built this way", or to understand the system in depth. Use it even if the user only says "document the architecture and the reasoning", "explain the design decisions", or "write the technical overview for a new engineer". For one technical reader who can already use the system — NOT a newcomer course (use learning-track), NOT operator recovery steps (use operations-runbook), NOT a look-up Q&A page (use project-faq).
imrohitagrawal/project-doc-skills · ★ 0 · AI & Automation · score 60

Install: claude install-skill imrohitagrawal/project-doc-skills

# Architecture & Decisions Walkthrough Builder Version: 1.3.0 · see `CHANGELOG.md`. Build the **depth artifact**: the document a new senior engineer reads to understand the system well enough to change it safely. It explains *how the whole thing fits together* and, for every choice that matters, *why it was made* — the alternatives considered, the trade-off accepted, and the failure modes it guards against. Read `references/house-style.md` first. **Diátaxis mode:** *explanation* (understanding-oriented). It is not a tutorial and not a step-by-step how-to; it builds the reader's mental model and judgement. **Sourcing — narrate, do not restate.** Draw from the repository, the decision records (ADRs), the decision log, the contracts, and the runbooks. The terse ADR registry owns the canonical decision *numbers and status* — link to it; this walkthrough teaches the *reasoning* a registry cannot. Apply the single-source rule in two parts: never restate an ADR number or status here (point to the live registry); and never copy a **tunable value** — a threshold, an `N`, a pixel ratio, a timeout — into the walkthrough. Name the value's *key* and link the ADR or config file that owns it. A pasted number drifts from its source the first time the source changes; a referenced key cannot. --- ## Before you start: what this needs, when to run it, where it fits This walkthrough is the **first artifact the rest of the documentation set is built on** — the learning track, the FAQ, the o