sea-generator-first

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*.json
• docs/specs/**/*.ir.json
• docs/specs/**/*.manifest.json
• docs/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

• references/decision-rules.md: spec vs generator vs last-mile routing.
• references/commands.md: validation, pipeline, fixture guard, and shared-context commands.
• references/common-failures.md: dataclass ordering, shared kernel, fixture guard, and misdiagnoses.
• scripts/generator_first_check.py: context path and command resolver.
• assets/spec-first-stop-and-ask.txt: standard escalation format.

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

1. 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.
2. Inspect only needed authority: specs, generators/templates, handwritten adapters/tests, and instructions.
3. Make the smallest source-authority change, regenerate if needed, and compare the generated diff to the intended outcome.
4. Check semantic fixture coverage whenever generated outputs change.
5. 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.