| name | sea-generator-first |
| description | Use when SEA work touches specs, generators, manifests, semantic fixtures, regeneration, `src/gen`, or behavior projected from ADR/PRD/SDS/SEA authority. |
SEA Generator-First
Keep SEA changes spec-first and honest about what generated code proves.
Core Rule
Specs and generators are authority. Generated outputs are projections. Never hand-edit:
**/src/gen/**docs/specs/**/*.ast*.jsondocs/specs/**/*.ir.jsondocs/specs/**/*.manifest.jsondocs/specs/**/fixtures/semantic/*.semantic.fixture.yaml- files marked
@generated, Generated by, or DO NOT EDIT
Wrong generated artifact means wrong spec or generator. Fix upstream, regenerate, verify.
Load Only What You Need
When To Use
Use when the request:
- changes
docs/specs/, .sea, .sds.yaml, manifests, fixtures, or regeneration
- touches
src/gen
- adds or changes a command, query, entity, event, port, policy, adapter, or context
- reports generated code as wrong, stale, missing, nondeterministic, or out of sync
- needs ADR/PRD/SDS/SEA traceability
Use sea-last-mile when generated contracts are valid but runtime wiring, adapters, persistence, or proof are missing.
Workflow
- Classify the fix target:
- Spec: source intent or contract changed.
- Generator: valid specs produce invalid or repeated bad output.
- Last-mile: contracts are valid but runtime behavior is missing.
- Stop-and-ask: generated edits, placeholders, or duplicate systems are requested.
- Inspect only needed authority: specs, generators/templates, handwritten adapters/tests, and instructions.
- Make the smallest source-authority change, regenerate if needed, and compare the generated diff to the intended outcome.
- Check semantic fixture coverage whenever generated outputs change.
- Name the honest classification:
authority-only, generated-contract, focused-slice, live-dev-proof, release-gate-proof, or enterprise-shippable.
Before editing, answer:
- Which generated surfaces should change?
- Which runtime slice will consume the generated contract?
- Which handwritten adapter, handler, service, or composition root implements it?
- Which command proves the generated contract reaches runtime behavior?
- Is the production composition root (
main.py, app.py, or equivalent) the importer — not a test fixture or local-mode branch?
- If events are involved, is the event publisher in the production composition root a real implementation (not
_NoopPublisher or a test fake)?
If the context mapping is unclear, run:
python .sea/skills/sea-generator-first/scripts/generator_first_check.py <context>
Quick Reference
| Situation | First move |
|---|
| New contract or domain shape | edit canonical SDS/SEA source, then pipeline |
| Generated code malformed across contexts | fix generator/template with regression coverage |
| Python dataclass default ordering fails | fix generator field ordering; do not mark optional fields required as a workaround |
shared context is confusing | use shared specs but expect generated code under libs/sea; see commands reference |
| Gap report shows missing adapters | switch to sea-last-mile after confirming generated contracts are correct |
| Generated surfaces changed | update non-generated semantic fixture scenarios and run the merge-diff guard |
Upgrading classification above generated-contract | confirm production composition root imports the contract: grep -r "from.*src.gen" services/ apps/ --include="*.py" | grep -v test — zero results means classification stays generated-contract |
| Event publisher in production composition | confirm it is not _NoopPublisher or a test fake; if it is, route to sea-last-mile before upgrading classification |
| Generated/handwritten boundary unclear | run grep -r "from.*src\.gen" src/ --include="*.py" | grep -v "^src/gen/" — expect zero results |
Stop And Ask
Stop for direct generated edits, placeholders, shims, duplicate stacks, inferred traceability, or shippability claims without runtime proof.
Use the standard wording in assets/spec-first-stop-and-ask.txt.
