Single entry point for the four canonical SDR types. Locates the
authoritative template in ~/repos/system-design-records/templates/,
copies it into the project's SDR directory, and hands off to the user.
The skill routes โ it does not redefine template content. The four
references/<type>.md files describe the routing surface (when to pick
each type, fields, checklist) โ they are NOT a fallback template body
and MUST NOT be substituted when the canonical template is missing.
-
Resolve template source. Check ~/repos/system-design-records/templates/
exists โ verify: test -d ~/repos/system-design-records/templates
- HALT on missing. Do NOT continue the procedure. Do NOT invent
template content. Do NOT use this skill's
references/<type>.md
files as a fallback template body โ they describe routing only.
Required emission: ask the user where the canonical templates live
(different path? not yet cloned?), and offer
git clone <repo> ~/repos/system-design-records. Resume only after
the user supplies a path that satisfies the test -d check.
-
Locate or create the project SDR directory. Search in this order:
sdrs/ (matches system-design-records global convention)domains/{Domain}/{System}/sdrs/docs/sdrs/ or docs/sdr/- Any directory containing files matching
NNNN-*.md
- If multiple matching directories exist: ask which one โ do NOT
silently pick the first match.
- If none exist: ask global vs domain-scoped, create accordingly.
- verify:
ls <chosen-dir> returns the directory.
-
Determine the next number. Scan existing SDRs, find the highest,
increment by 1, pad to 4 digits. Sub-numbers 0008.1 allowed for
related decisions โ ask before assuming.
- In a shared repo, suggest the user
git pull first to avoid
concurrent-author number collisions; this is advisory, not enforced.
- verify: filename
NNNN-<kebab-title>.md does not collide locally.
-
Resolve template filename and copy. The four type slugs
(system-overview, service-component, data-design, blueprint)
map to filenames in ~/repos/system-design-records/templates/ but
the upstream filename convention is NOT pinned by this skill โ
resolve at runtime:
- List the directory:
ls ~/repos/system-design-records/templates/
- Match the requested type to an actual filename (e.g.,
system-overview may map to system-overview.md,
system_overview.md, or similar โ accept any close match,
case- and separator-insensitive).
- If exactly one matches โ copy it to
<sdr-dir>/NNNN-<kebab-title>.md.
- If zero or multiple match โ STOP and ask the user which file maps
to the requested type. Do NOT guess.
- verify: copied file exists, has non-zero size, AND its path was
listed by the
ls above (not synthesized).
-
Fill metadata header. Title, date, author, responsible architect,
contributors, lifecycle stage (POC/Pilot/Beta/GA/Sunset), status
(Proposed by default). Read the per-type reference
for fields specific to that template.
- verify: metadata header has no unfilled
<...> placeholders.
-
Open the file and tell the user to fill the body. Suggest invoking
the decision-challenger agent (devil's advocate for SDRs) once the
draft is substantial โ it stress-tests assumptions, second-order
effects, and stakeholder coverage.
-
Glossary hooks (end-of-skill). After the artifact body is filled,
fire two hooks against ./CONTEXT.md. Both fire once at
end-of-skill (not per-section) per the
2026-05-22 decision
and the contract in
references/CALLER-HOOKS.md ยง sdr.
Read hook runs first so its findings can inform what the write-offer
surfaces as new terms.
a. Read hook (advisory). If ./CONTEXT.md exists and parses
cleanly, parse the ## Language section, build the _Avoid_:
alias set, scan the artifact body, and surface one advisory line
per match โ only when an artifact term hits an _Avoid_ alias
(only-on-conflict). NEVER substitute silently in either direction
โ CONTEXT.md is a candidate, not authority. Surface candidates
for user judgment per rules/memory-discipline.md (verify before
assert). Silent no-op if ./CONTEXT.md is absent or malformed.
b. Write-offer hook. Scan the artifact for component / system /
data-source names that recurred โฅ2ร and lack a ./CONTEXT.md
entry. Invoke
/glossary --offer-from-caller=sdr --candidate-terms=<...> โ
offer never auto-write. Skip if every candidate is already
canonical.
Both hooks are advisory, not blocking. Promotion to blocking is
gated by Phase B eval signal per the decision doc rollback trigger.
