System Architecture
When to use
- You have approved requirements and the work is not trivial: a new subsystem, several components, real integration.
- Skip a small feature; keep its structure in its own task or plan rather than writing a separate architecture document.
- This skill owns the target system's structure.
migration-strategyowns how an existing system reaches that target;verification-strategyowns the set of checks the whole initiative runs.
Step 1: Trace and structure
Open assets/architecture-section.md before starting. Fill a section only
with what this work has; the template says what an empty one carries.
- Map every requirement, preserved obligation, and significant risk to the component, the interface, and the owning gate reference that cover it. Its owner defines the gate elsewhere; define no assurance gates here. Look each gate reference up where its owner keeps it: a placeholder, an invented ID, or a gate that does not exist there leaves its row unmapped. If a row is unmapped, approval is blocked.
- Name each module by what it does and by what it does not do. If removing it would spread its complexity across its callers, it stays. If the complexity would merely move elsewhere, merge it. Before adding a module, search the tree for one already doing that job and record the search.
- For each dependency and each asynchronous path, write its timeout, its retry and idempotency, what still works when it is degraded, how it recovers, and how each is exercised (the test, fault injection, or drill).
- Every sentence that states what the existing system does today (a
component exists, a call site handles a case, a format carries a field,
a dependency defaults to a value at its pinned version)
names the path and symbol it was checked against at the current
revision. Rewrite one you cannot cite to what is known, or invoke
clarifying-intentfor it. The plan's tasks are written against these sentences as facts.
Step 2: Operational views and seams
- Cover each operational view the template lists that affects correctness. The transition procedure belongs to the migration contract; do not restate it here.
- If a view is left out, write a skip record with the fields the template's operational-views table lists. Never drop a view as "inapplicable" without one.
- Place a seam only for repeated behavior with a stable owner and measured change friction, or for one real volatile or external boundary with measured impedance, a failure policy, or test isolation. Variation that is only hypothetical earns none.
- If a choice is hard to reverse, invoke
architecture-decisions; a choice it skips stays in theLoad-bearing decisionsrow. If a choice that would change the design is unresolved, invokeclarifying-intent.
Step 3: Write, review, present
Write the section to
.sdlc-skills/designs/{{YYYY-MM-DD}}-{{topic}}.mdor the user-set path and fill every field of the template's header and its high-risk classification block; once its identity is issued, the section is never edited. Record that identity in its ledger (the decision record: add to it, never rewrite it, and keep it outside the design).If any answer in that block is off the ordinary route, or the user marks the work high-risk, fill
assets/design-review.mdbefore presenting and dispatch it asdispatching-parallel-agentsStep 2 says; its not-dispatched question omits the self-review option. That review is blocking. OnNEEDS_CONTEXT, supply the path it names and rerun once. A blocking finding takes one successor section and one re-review; report what is still open to the decision owner and end the turn. The owner accepts a finding only by naming it: recordaccepted by {{owner}}with the finding in the ledger, and present once every open finding is accepted or corrected. A reply that names none accepts none.Present:
{{Section}} {{path}} — version {{identity (per template)}} {{summary lines}} 1. Approve and hand off to planning 2. Request changes 3. Reject 4. Cancel Recommendation: {{option}} — {{one sentence}}.Ask this and end the turn;
clarifying-intentowns what closes it.If option 1 is chosen and every design section the work needs is approved, REQUIRED SUB-SKILL: invoke
writing-plansagainst this version. If a needed section is not approved yet, invoke its owning skill instead.
Gotchas
- A design sentence about the existing system that cites nothing is planned as a fact: a design that said a command launched a flow reached implementation before a worker found nothing launched it on the base, and the plan grew a task mid-run. Step 1.4 cites the path and symbol.
- Step 1's mapping table needs a real owning gate for every row, but this skill defines no assurance gates itself. A row that names a placeholder, or a gate its owner never defined, still reads as mapped on the page; only the lookup in Step 1 shows that it is unmapped.
- The Skip condition in When to use is checked once, at intake. Nothing here re-checks it as scope grows, so a feature that starts small and later crosses into several components can stay embedded in its task plan instead of getting this skill's own architecture record.