sdd-architecture-scan

/sdd-architecture-scan — Deep Architecture Scan

The user may name a focus path after the command; then every phase below applies to that subtree only, and the final merge touches only its entries.

Speak plainly, in DocLanguage, throughout: assume the user has never seen this workflow. Every question and every gate opens with one short line saying why it is asked and what the answer changes, and every term of art (worklist, unit, tier, scout) gets a one-clause introduction on first use. Minimal and precise — one line of why, never a lecture.

Where am I? (state router — the files decide, not the conversation)

• No .sdd-scan/_worklist.md → run Phase A, then stop at the worklist gate.
• Worklist exists with pending units → run Phase B on pending units only.
• All units done but the update merge not yet confirmed → run Phase C. The user saying "distill what we have" also runs Phase C — a full re-distillation from the reports, even after a confirmed merge; refreshing dates or markers alone is not a distillation. Otherwise, after a confirmed merge, a re-invocation has nothing left but the cleanup question.

On a fresh start — say what this buys and costs (once, in DocLanguage)

On a fresh start (no worklist yet) this briefing is the first visible output — before any question and before Phase A runs, and equally when /sdd-setup routed here. Three short, plain points (~6 lines total), then proceed:

• Value: the fingerprint replaces exploration. Agents in every later session — in both tools — jump straight to the right place instead of searching, and technical planning (specs, reviews, onboarding) starts from a shared, verified map.
• Cost: the scan is token-intensive — scouts read code in isolated contexts. Name a planning figure (~50k tokens per analysis unit; large repositories multiply), say that cost scales with the models in use and can get expensive, and that a capable model pays off for synthesis while the scouts inherit the session model — choosing a cheaper model for the scan session, or pinning one locally in the scout agent files, is the biggest cost lever.
• Levers: the worklist gate is the cost dial — defer units (they stay visible under unmapped:), set shallow tiers for periphery, rescan later with a focus path; the scan resumes from its files at any point.