# To Ssot

> ---

- Skill: `together2329/to-ssot-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add together2329/to-ssot-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/together2329/to-ssot-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: together2329 (https://skillmd.com/u/together2329)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/together2329/to-ssot-2

---

---

## name: to-ssot

description: Synthesize the current conversation context (and codebase understanding) into a canonical SSOT YAML, including function_model and cycle_model, and write it to /yaml/.ssot.yaml. Use when the user wants to convert a finished discussion or grill-me session into a concrete SSOT YAML file.

# To SSOT

Take the current conversation context (typically the output of a `grill-me`
session) and produce a complete SSOT YAML file conforming to the project's
canonical template. Adapted from
[https://github.com/mattpocock/skills](https://github.com/mattpocock/skills) (`to-prd` / `to-issues`, MIT) —
issue-tracker output replaced with a YAML write, story breakdown replaced
with the SSOT section schema.

This skill **does not interview the user** — synthesize what you already
know from the approved Plan Mode / grill-me context. If a field affects
RTL behavior and is unknown, do not invent it and do not hide it behind a
template default. Stop with `[SSOT QUESTION] -> user` or record a
non-blocking conservative assumption in `custom.assumptions`.

Approved QA may come from a human answer or from explicit `auto-select` mode.
When it came from auto-select, preserve the fact in `custom.assumptions` or the
handoff summary so reviewers can audit the generated SSOT before signoff.

If `/import` was run first, use `<ip>/req/import_manifest.json`,
`<ip>/req/extracted_decisions.json`, `<ip>/req/imports/`, and
`<ip>/wiki/import-evidence.md` as evidence. Do not treat imported RTL as the
production output of this workflow; convert only the confirmed facts into SSOT
fields.

`/to-ssot` is an execution step. Do not call `todo_write` here; it is
Plan Mode only and will be rejected in Normal mode. If progress tracking is
useful, use a short prose ledger or `todo_add`, then immediately read/write
the SSOT and run validation.

## RTL TBD Feedback Mode

If the current context contains `[SSOT TBD REPORT] -> ssot-gen`, run targeted
enrichment instead of rewriting the whole SSOT:

1. Parse each `Missing` row: `yaml_path`, `needed_for`, `question`, and
  `current_rtl_action`.
2. Read the existing `<ip>/yaml/<ip>.ssot.yaml` once.
3. Patch only the named YAML fields when the missing fact is available from
  the conversation, requirements, imported documents, or approved QA.
4. If the fact is still unknown, record a pending QA item for that exact
  `yaml_path` and `needed_for` instead of inventing a value.
5. Validate the patched SSOT and emit a refreshed `[SSOT HANDOFF] -> rtl-gen`
  with `Resolved RTL TBD rows: N` and any `Pending QA rows: ...`.

## Process

1. **Locate the canonical template.** Read
  `workflow/ssot-gen/rules/ssot-template.yaml` to confirm the section
   ordering and field names you must use. (It's also embedded in the
   ssot-gen system prompt.)
2. **Resolve the IP name.** Take it from the latest user message, an
  existing `<ip>/` directory, or the first `top_module.name` referenced
   in conversation context. Refuse if the name is ambiguous — ask the
   user once.
3. **Sketch the section map** internally. For each canonical section,
  note: filled / partial / missing. Sections grill-me typically resolves
   the user-facing behavior and interface anchors first; remaining signoff
   sections come from explicit requirements, approved assumptions, or
   conservative repair defaults that are visible in provenance.
4. **Use the Preview/validator YAML shape exactly.**
  - Top level is one YAML mapping. Do not wrap the document in `ssot:`,
   `sections:`, `spec:`, or markdown fences.
  - Use these exact top-level keys, in this order:
  `top_module`, `sub_modules`, `decomposition`, `rtl_contract`,
  `parameters`, `io_list`, `features`, `dataflow`, `function_model`,
  `cycle_model`, `clock_reset_domains`, `cdc_requirements`,
  `rdc_requirements`, `registers`, `memory`, `interrupts`, `fsm`,
  `timing`, `power`, `security`, `error_handling`,
  `debug_observability`, `integration`, `dft`, `synthesis`, `pnr`,
  `coding_rules`, `reuse_modules`, `custom`, `dir_structure`,
  `filelist`, `test_requirements`, `quality_gates`, `traceability`,
  `workflow_todos`, `generation_flow`.
  - Do not use legacy top-level aliases such as `interface`,
  `bus_interface`, `register_map`, `clock_reset`, `errors`, `debug`,
  `dv_plan`, or `verification_plan`.
  - SSOT Preview renders typed cards from `top_module.description`,
  `io_list.interfaces[].ports[]`, `function_model.transactions[]`,
  `cycle_model.pipeline[]`, `cycle_model.scenarios[]` or
  `function_model.scenarios[]`, `registers.register_list[]` or an
  explicit no-register policy, `fsm.states/transitions` or an explicit
  no-FSM policy, and `test_requirements.scenarios[]`. Treat these as
  required for a previewable engineering SSOT.
5. **Write executable workflow todos.** Preserve and enrich
  `workflow_todos.<stage>[]` as the downstream handoff ledger. Every
   executable item must include `id`, `content`, `detail`, `command`, `script`,
   `instructions`, `criteria`, `source_refs`, `priority`, and `required`.
   Use `command` for the ATLAS slash entrypoint (`/to-ssot <ip>`,
   `/ssot-rtl <ip>`, `/ssot-tb <ip>`) and `script` for the deterministic
   workflow script that validates or expands that handoff. The todo detail and
   instructions must be IP-specific and source-backed; do not leave generic
   template text when import evidence exists.
6. **Fill the YAML generically from the approved context.**
  - Do not use IP-specific fixed templates.
  - Required behavior fields must come from the conversation, local requirements, or explicit assumptions.
  - List sections preserve the order grill-me elicited them in.
  - Include enough detail for downstream generic workflows:
  interfaces, parameters, memories, registers/no-CSR policy, interrupts,
  function_model transactions/invariants, cycle_model latency/handshake/
  pipeline rules, FSM states/transitions, feature triggers/datapaths/
  outputs, timing/power/security/error/integration/DFT/synthesis
  constraints, reset defaults, error behavior, test scenarios, expected
  results, scoreboard checks, coverage goals, quality gates, and traceability.
  - For every interface, include machine-readable protocol/timing/handshake
  rules in addition to ports. Port declarations alone are not enough.
  - For every register field, include bit range, access, reset, description,
  reserved behavior, and write/clear side effects where applicable.
  - Split coverage into `coverage_goals.function` and
  `coverage_goals.cycle`; each must have target, model, bins, source_refs,
  classes, and descriptions.
  - Comments are optional; do not add `TODO` comments for behavior that
  rtl-gen needs. Ask/stop instead.
7. **Write the file.** Path is exactly `<ip>/yaml/<ip>.ssot.yaml` from the
  project root. Do not add a second `<ip>/` segment when the UI scope is
   already set to that IP; for `gpio`, the path is `gpio/yaml/gpio.ssot.yaml`,
   never `gpio/gpio/yaml/gpio.ssot.yaml`. Use `write_file`.
   Scaffold output containing `<TBD>`, `<placeholder>`, `TODO`, or a tiny
   template-only YAML is not user-authored content; replace it with the
   complete canonical SSOT. For a substantive existing SSOT, read it first
   and preserve user-authored facts while completing missing sections.
8. **Validate before final handoff.** Use the workflow validators:
  first run `python3 "$ATLAS_WORKFLOW_ROOT/ssot-gen/scripts/repair_ssot_schema.py" <ip> --root "$ATLAS_PROJECT_ROOT" --mode engineering`,
   then run `python3 "$ATLAS_WORKFLOW_ROOT/ssot-gen/scripts/verify_ssot.py" <ip> --root "$ATLAS_PROJECT_ROOT" --mode engineering`.
   `verify_ssot.py` also runs `check_ssot_disk.sh` and writes
   `<ip>/req/ssot_validation.json`. If validation fails, fix the YAML and
   rerun. Do not run RTL/TB generators from ssot-gen.
9. **Summary.** After writing, list:
  - the path written
  - which sections came from conversation vs. template defaults
  - any `# TODO: confirm` lines that need follow-up
  - whether validation passed
10. **Suggest next steps.** Use `/ssot-rtl <ip>` after the SSOT validates,
  or another `/grill-me` round if blocking behavioral fields are missing.

## Bounded execution rule

`/to-ssot` must make forward progress with real file tools. The allowed
discovery budget for one run is:

- read the canonical template at most once;
- read the existing `<ip>/yaml/<ip>.ssot.yaml` at most once;
- read the validator at most once, only if its requirements are not already
included in the prompt;
- then the next tool action must be `write_file`, `replace_in_file`, or
`run_command` validation if the file was already complete.

If an existing SSOT is substantive, prefer a targeted patch over rewriting the
whole file. Insert or replace only the missing/weak canonical sections, preserve
approved facts, then run the exact validator. Re-reading the same template or
same SSOT after identifying the missing section list is a workflow failure; use
that turn to write or patch the file instead.

For large YAML outputs, do not narrate the entire file in prose first. Emit the
file tool call directly. Validation output is the proof, not an explanation of
why the YAML should pass.

## Output template (header)

```yaml
# =============================================================================
# SSOT — <ip_name>
# Generated: <iso-date> · source: grill-me + to-ssot
# =============================================================================

top_module:
  name: "<ip_name>"
  version: "1.0"
  type: "<dma|cpu|accelerator|bus|peripheral|memory>"
  description: "<one-sentence purpose>"
  target:
    technology: "generic"
    clock_freq_mhz: 500
```

(Continue with the remaining canonical sections from `ssot-template.yaml`.)

## Do NOT

- Do not rewrite existing user-authored prose; preserve their phrasing
in `description` fields where they gave one.
- Do not invent register addresses, bit positions, protocol timing, memory
depth, security transforms, DFT obligations, PPA targets, quality gates, or
expected outputs. Ask or record a clearly non-blocking assumption.
- Do not run code generators, deterministic fallback writers, Jinja2
expansion, RTL generation, TB generation, lint, or simulation. Those are
downstream workflows.