arch-skill

name	arch_skill
description	Formalize architecture planning into a single, iterative workflow and produce one canonical architecture document (no doc sprawl). Use for architectural changes, refactors, or new system design.

arch_skill

Purpose

This skill turns architecture work into a repeatable, interactive process that yields a single high‑quality architecture document. It prioritizes clarity, falsifiability, and execution readiness.

Primary outcome

A single canonical architecture document that:

• Follows the template in docs/arch_skill_raw_notes.md.
• Captures research grounding, current/target architecture, call‑site audit, phased plan, test strategy, rollout, and decision log.
• Is updated throughout execution and remains the single source of truth.

Operating rules (non‑negotiable)

1. Single‑document rule: Every architectural discussion is worked out in one doc (the canonical architecture document). Do not create multiple planning docs or split phases into separate files. References are allowed, but planning and decisions live in the single canonical doc.
2. Code is ground truth: Internal references must point to code paths and runtime behavior. No speculative claims without anchors.
3. Phase‑gated workflow: Research → Architecture → Implementation plan → Execution. Pause for user sign‑off between phases.
4. Explicit invariants: Call out stop‑the‑line invariants and acceptance tests early.
5. No parallel solutions: Avoid competing sources of truth or duplicate patterns.

Inputs

• Target repo path and change request.
• The architecture template: docs/arch_skill_raw_notes.md.
• Access to internal code and external references.

Execution flow (high level)

• Phase 1 — Research: gather internal/external anchors and open questions.
• Phase 2 — Architecture: define North Star, current + target architecture, tradeoffs, call‑site audit.
• Phase 3 — Implementation plan: phased plan + tests + rollout/telemetry.
• Phase 4 — Execution: implement iteratively, update the canonical doc as work progresses.

UI work requirement

If the architecture touches UI/UX:

• Include ASCII mockups for current and target states in the canonical doc.

Interaction protocol (lightweight)

• Ask for clarification only when there are multiple viable options or the request is ambiguous.
• If there’s a single obvious path, proceed without blocking.
• When asking, present 2–4 concrete options and a recommended default.

Alignment checkpoints (lightweight)

• End of Phase 1: ask if research is sufficient only if there are unresolved forks.
• End of Phase 2: ask for sign‑off only if target architecture has open tradeoffs.
• End of Phase 3: ask for sign‑off only if plan sequencing/rollout is still in question.
• End of Phase 4: ask for confirmation of outcome vs North Star.

Where to start

• Read: docs/arch_skill_skill_outline.md
• Use: docs/arch_skill_raw_notes.md as the canonical architecture doc template.