ssot-preflight ยท diff

git:20261026.4713c7f to git:20261027.8fc8635

12 added, 48 removed. Audit A to A.

---
name: ssot-preflight
description: Read the repository's SSOT before substantive work. Use this before code, config, documentation, review, debugging, refactoring, or planning work in a repository, to find the invariants and documents that bear on the task and to surface open questions that affect it. Skip it for non-repository chat, pure command runs, and typo or formatting edits that cannot change meaning.
metadata:
- protocol_version: "3.1"
+ protocol_version: "3.2"
bundle: "SSOT Skill"
---
# SSOT Preflight
- Before substantive work, find out what the repository's memory says about the
- task. Read [`references/memory-model.md`](references/memory-model.md), which
- explains what `SSOT/` holds and what the invariants register means, the
- first time you use SSOT in a session.
+ Before substantive work, find out what the repository's memory says about the task. Read [`references/memory-model.md`](references/memory-model.md), which explains what `SSOT/` holds and what the invariants register means, the first time you use SSOT in a session.
## 1. Find the entry point
- - **No `SSOT/` directory.** Tell the user the repository has no SSOT and offer
- to create one with `$ssot-bootstrap`. Setup writes a documentation tree and
- can take more than one session, so it needs the user's yes. If they decline
- or defer, do the task without the SSOT steps, and do not offer again this
- session.
- - **`SSOT/BOOTSTRAP.md` exists.** Setup is unfinished. Offer to continue it,
- and meanwhile use what is already written.
- - **`SSOT/README.md` has no `ssot_format: 3`.** This SSOT predates v3:
- usually the v2 layout with `SSOT/STATUS.md`, sometimes a hand-written one.
- Read it as knowledge. Its coverage labels and review
- records are historical, but its adjudications, user constraints, limits,
- and open questions that bear on the task still bind you. Do not write to
- it. Tell the user once that `$ssot-bootstrap` can migrate it or set it up
- in the v3 format.
+ - **No `SSOT/` directory.** Tell the user the repository has no SSOT and offer to create one with `$ssot-bootstrap`. Setup writes a documentation tree and can take more than one session, so it needs the user's yes. If they decline or defer, do the task without the SSOT steps, and do not offer again this session.
+ - **`SSOT/BOOTSTRAP.md` exists.** Setup is unfinished. Offer to continue it, and meanwhile use what is already written.
+ - **`SSOT/README.md` has no `ssot_format: 3`.** This SSOT predates v3: usually the v2 layout with `SSOT/STATUS.md`, sometimes a hand-written one. Read it as knowledge. Its coverage labels and review records are historical, but its adjudications, user constraints, limits, and open questions that bear on the task still bind you. Do not write to it. Tell the user once that `$ssot-bootstrap` can migrate it or set it up in the v3 format.
## 2. Read what this task needs
Read `SSOT/README.md`, then:
- 1. **Invariants.** Find the rows whose rule this task could affect, and read
- the explanation each one links to. If the task would break a confirmed
- invariant, stop and ask the user before acting. Follow candidate rows by
- default. If the task needs to depart from one, or its meaning is unclear
- in a way that matters here, ask the user to confirm or drop it and record
- the answer; only the choice that depends on it waits.
- 2. **Open questions.** If one blocks the path this task needs, say so. Only
- the work that depends on the answer waits; unrelated work goes ahead.
- 3. **Known traps and limits.** Read the gotchas and the known gaps that
- touch the parts you will change, and handle each one: fix it, work around
- it deliberately, or say why it does not apply.
- 4. **Routes.** Read the files the task routes point to. If no route fits, read
- the product and architecture entry documents. Do not read the whole tree.
- 5. **What you rely on.** When an SSOT statement decides how you will implement
- something, check it against the code first. If they disagree, the code is
- the current behavior. Note the mismatch so closeout fixes the document, or
- so you can report the violation.
+ 1. **Invariants.** Find the rows whose rule this task could affect, and read the explanation each one links to. If the task would break a confirmed invariant, stop and ask the user before acting. Follow candidate rows by default. If the task needs to depart from one, or its meaning is unclear in a way that matters here, ask the user to confirm or drop it and record the answer; only the choice that depends on it waits.
+ 2. **Open questions.** If one blocks the path this task needs, say so. Only the work that depends on the answer waits; unrelated work goes ahead.
+ 3. **Known traps and limits.** Read the gotchas and the known gaps that touch the parts you will change, and handle each one: fix it, work around it deliberately, or say why it does not apply.
+ 4. **Routes.** Read the files the task routes point to. If no route fits, read the product and architecture entry documents. Do not read the whole tree.
+ 5. **What you rely on.** When an SSOT statement decides how you will implement something, check it against the code first. If they disagree, the code is the current behavior. Note the mismatch so closeout fixes the document, or so you can report the violation.
## 3. Before your first change, and while you work
- If the user has stated a lasting rule ("from now on", "never", "always"), or
- settled a decision whose reason exists only in the conversation, write it to
- its owner before you change anything else, and again whenever the user
- settles one later. Follow closeout's rules for where and whether SSOT may be
- written, and label what the code does not do yet as planned. These do not
- wait for closeout: an interrupted or compacted session loses them, and the
- code never shows them. An idea still under discussion is not settled.
+ If the user has stated a lasting rule ("from now on", "never", "always"), or settled a decision whose reason exists only in the conversation, write it to its owner before you change anything else, and again whenever the user settles one later. Follow closeout's rules for where and whether SSOT may be written, and label what the code does not do yet as planned. These do not wait for closeout: an interrupted or compacted session loses them, and the code never shows them. An idea still under discussion is not settled.
- Watch for the other facts that will outlive the task: decisions, changed
- contracts or behavior that users rely on, traps you hit, changed commands,
- and temporary workarounds. Note them as they come up; `$ssot-closeout`
- records them before you finish, and you may update an obvious owner right
- away.
+ Watch for the other facts that will outlive the task: decisions, changed contracts or behavior that users rely on, traps you hit, changed commands, and temporary workarounds. Note them as they come up; `$ssot-closeout` records them before you finish, and you may update an obvious owner right away.
## Where to go next
| Situation | Skill |
|---|---|
| No SSOT yet, setup unfinished, or a v2 layout to migrate | `$ssot-bootstrap` |
| Finishing a substantive batch, before the final response or commit | `$ssot-closeout` |
| Health check, a review, or catching up on past commits | `$ssot-doctor` |